


Institutional Archive of the Naval Postgraduate School 


Calhoun: The NPS Institutional Archive 
DSpace Repository 


Theses and Dissertations 1. Thesis and Dissertation Collection, all items 


1982 


Software engineering practices: their impact 
on the design of a program maintenance manual. 


Teuscher, James Howard. 


http://ndl.handle.net/10945/20339 


Downloaded from NPS Archive: Calhoun 


Calhoun is the Naval Postgraduate School's public access digital repository for 


' (8 D U DLEY research materials and institutional publications created by the NPS community. 
: Calhoun is named for Professor of Mathematics Guy K. Calhoun, NPS'‘s first 
ath 
KNOX appointed — and published — scholarly author. 


i LIBRARY Dudley Knox Library / Naval Postgraduate School 


411 Dyer Road / 1 University Circle 
Monterey, California USA 93943 








http://www.nps.edu/library 







a | “ss = 
- | @ 
J ' 
LS es , 
= i i 
5 1 re) = 
i ——_ it 
- iver — = 
' : ; 
Le 
i wal be at ty 
\ “ 
‘ar ~ 
= -& Ss =! 
a ; = - 
Ly ; ' 
i Bn ~ 
4 
Tel a= 
Cee = j ey 
As i ' 
Vf at 
en Ut 
a7 
7F 
i) 
at 
af 
ry 1) * + 
—_ ‘ ! 
—_— = 7 | 
i = 
| 
- 
, 
&> 
7 
= 
J 
1, 
| 
' 
] 
a. 1 
i] 
¥ 
a 77 A 
| 
t 
= 
Vv 
ath u ‘ 
af ; 
ane 4 : 
on af . 5 
i} i} A 
i i = | 
1] | 
' - i 
i; ie "Tt , J 
' ' A ‘ 

' ‘\ ' ‘ ee = 
» i= | : = 
— ar AOC r ‘a it- sie 

vk 5% rT a 7f ali = - 
: 7 ’ < Pity if i 
é il | i 
kT a ae | 
ros 6 2 Th) | _ 


i 
an tt ya 


seanue 7) atk Thi \ 


1 


AVAL posTGRADUATE scHoOL 


MONTEREY, CA 93940 











NAVAL POSTGRADUATE SCHOOL 


Monterey, California 





Tae S15 


SOs ke ENGINEERING PRACTICES: 
ieee PACT ON THE DESIGN OF A 
PROGRAM MAINTENANCE MANUAL 


by 


James Howard Teuscher 
December, 1982 


Thesis Advisor: Ron Modes 





Memroved sor Public Re leases Distribution» Unlimited 


7208808 








SECURITY CLASSIFICATION OF THIS PAGE (Wren Data Entered) 


REPORT DOCUMENTATION PAGE 


2. GOVT ACCESSION NO 






READ INSTRUCTIONS 
BEFORE COMPLETING FORM 


3. TYPE OF REPORT € PERIOO COVERED 
Master's Thesis 
December, 1982 


6. PERFORMING ORG. REPORT NUMBER 


8. CONTRACT OR Garant NUMBER(e) 






4. TITLE (and Subttrie) 


software Engineering Practices: 
Their Impact on the Design of a 
Program Maintenance Manual 



















7. AUTHOR ea) 


James H. Teuscher 















10. PROGRAM ELEMENT. PROJECT TASK 


AODORESS 
9. PERFORMING ORGANIZATION NAME ANO AOORES AREA & WORK UNIT NUMBERS 


Naval Postgraduate School 
Monterey, California 93940 















12. REPORT OATE 


December, 1982 


ee ge Be 


16. SECURITY CLASS. (of tnte report) 


11. CONTROLLING OF FICE NAME AND ADORESS 
Naval Postgraduate School 
flemeerey, California 95940 









. MONITORING AGENCY NAME @ ADORESE(I different from Cantroiling Office) 











UNCLASS Fr DED 


Se. OECLASSIFICATION/ OOWNGRADING 
SCH EOULE 
OCIS TRIBUTION STATEMENT (of thfe Repert) 


Approved for Public Release; Distribution Unlimited 





r tw DISTRIBUTION STATEMENT (ol the abetrect entered in Block 20, If different trom Report) 


- SUPPLEMENTARY NOTES 





KEY WORDS (Continue on reverese side if neceseary end identify wy sieck number) 





Software Engineering, Software Documentation, Maintenance 
Manual, Structured Programming 










20. ABSTRACT (Continue an reveres eide if necesceary and idenitty by block mmber) 





The cost of software is fast becoming a major slice of DOD's 
automated data processing budget. Most of this cost is eli momere 10: 
related to the maintenance of existing software. <A primary cause 
iS poor or non-existent documentation which Meads COunton COS ts 
when it comes time to change the software to correct errors, 

add enhancements, or to comply with changes in Federal regulations 
DOD policies. (Continued) 









DO , ae 1473 = EDI TION OF | NOV 6813 OBSOLETE 


S/N 0102°014- 6601 | oo > a Enrered) 








| 


ranean reenter area tener 
Secumve Ci. 4E81F1C2V1GNM OF Vets PaGsren Nora Ensoved 


ABSTRACT (Continued) Block # 20 


This thesis looks at the various software engineering techniques 


available to programmers and managers for the development of soft- 
ware documentation. 


A set of guidelines for an "ideal" program 


maintenance manual 1s proposed. These guidelines are based on 
current DOD standards, examples of software maintenance manuals 
from industry, and applications of current software engineering 


practices. 
BD Form 41473 
a, ee 


a — a 








Approved for public reieasa; distribution unlimited. 


Software B AgRRE SE. BS Practices: 
Their Impact on the Design of a 
Program Maintenance Manual 


by 


_ dames Howard Teuscher 
| Lieutenant, United States Navy 
BoA, State University of New york, College at Oswego, 1975 


Submitted in partial fulfillment of the 
requirements for the degree of 


MASTER OF SCIENCE IN INFORMATION SYSTEMS 
from the 


NAVAL POSTGRADUATE SCHOOL 
December 1982 





ABSTRACT i 


The cost of scftware is fast becoming a najor slice of DOD's 
Pieomme-a 8Gad-a PEOGeSsSing budijyet. Most of this s3st is 
~rectiy related to the mainteraance of axisting software. A 
primary cause is poor or non-2xistant ioctumentation which 
leads t> high costs whan it cones time t> change the soft- 
Mace tO COLrect errors, add enhancements, 25 to ceo@oly with 
changes in Federal regulations/DOD polici:2s. 

This thesis looks at the various software engineering 
techniques available to programmers ani managers for the 
development of software docuneatation. A set of guidelines 
tor an "ideai™ program maintenance manual is propos2i. These 
Guidelines are based on current DoD staniards, exanaples of 
software maintenance manuals from industry, and applications 


of current software engineering prastices. 
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I. INTRODUCTION 


Aw THE NEED FOR DOCU AENT ATION 


{ 


| 
A recent Govenment Accountiig J£ffice report, 


reviewing 
computer software maintenanc® in Faidier2l ADP agencies, 


producei some interesting observations “Raf. 1}. 


1. Pwo thirds of the programmers at 13 Federal ADP agen- 
cles spent their time on softwar2> naintenance. 


2. The Department of Deféens2 will spend approxinately 33 
Viton on, 198 1 on Sorcwa re. 


3. Agencies have made little effort to effactively 
manage and minimize the resdurces czquired tS nain- 
tain computer software. 

eee aware TS Often Wdineained by o25ple whe did rot 
aevelop i=. 

See ooe GOCUMertection Oftsa results in rebuilding 43 
2ntaire SyYScem OL programs becauss understaniing ane 
modifying an existing prdgram may be more troabie and 


expense then buiiding 2 néw one. 


One fed=ral Governmant is not alon2 in its softwate nazi 


ct 
1?) 


memcervere=es'. All ADP users, including private iajiusétry, 


are béing swallowed up by the "tar-pits 2f software nan2zge- 
ale 


men+" as rred Brooks tas so vividly described [Ref. 2]. he 
Besees 2-2 the government and privats industry, 2n tems of 


doilars and manpower, is increasing 
Costs for software (procurenant a 
manec-egmeor reach 2200 ballion by 19 
feel sp=ncms50 “Sbillivenm@by 1990e£0r e¢ 
lfexem. 3,4 }. 


Modazqe share OL these Cds2sS aE [95 SoOttwere™aelate- 
mance (see Figure 1.1). (ease csclat=S have Shown tha 
Teiom COr=zy <O ninety-five perceat of manpodver effort in mos* 
ADP organizezions is spent on software Ma2iatcenancs 


f{Ref. 5-14 }. 





a me ee aS A: Te A RS 


| 
















{ 
{ MANPOWER (PEOPLE/YA} 
il 
SYSTEMS FUNCTIONAL ‘ | 
DEFINITION | DESIGN, SPECIFICATION DEVELOPMENT OPERATION AND MAINTENANCE 
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Figure 1.1 Manpower Loading and Maintenance costs. 
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There are many reasons for the wiid2 variation ia effort 
b2ing devoted to software maint2narnce, howaver, a definition 
of maintenance should be presented first. Software nainte- 
nance is best defined as: 


That activity which is cons ecned with aaking changes t 
software for the purpose of Lmproving 2 SOEs ieee the 
software without inttoduciag aew 2rrors fRef. 15]. 


Despite the fact that large amounts of nanpower and other 
resourc?s are spent on softwars maint2naace, few nanagers 


comprehend the underlying reasons. Th2ar3 are four basic 


issues behind the problems of software naintenance: 

® Maintenarce LS Gensider=d less glamerous, interesting 
em Chal Boe @s compared ¢t95 ,3ystem design anda 
PEogranning; ence, trsre @2s Jab tle 2ncenmwe) Lor 
computer personnel to become involved in _ maintenance 
activities (or dccument their time ani effort spent on 
maintenance). 

e During development it is Be: tOO arly ir the progeex 
PeptoOrsee problens whi ein GECCULr ising maznt snanesc: 
aS a consequences maz Leatnabi a (on meperuy, Sf Soie- 
ware whic makes maintena ATC Ve eS, S257 =O 
PesrOrm) is not provided f5r i “tha system design. 

e Pra ject management does not always recognize that. main- 
Poemability consideretions shouid bs an integral part 


hn 


of the design process. 


{ 


seit is oe (eel ieuwe cto moda or semolity eh> stauc= 
Mime OL DIOgGram after tae program has deen Wlitten. 

{ Ret. 15 
Weapon system software and rzal-tins system softwars 
used extensively by «he Deparctmant of Defs2 (DOD) sufiers 
Beem S2latar problems [Ref. 16}. Demo eRe r. 17 | me poxss 
mya2= aALr Force avionics software costs about 5/5 Den 
Prcoierucs: on to daveicp, but Maintenance tosctsS ars arsund 
MepeOumpe re 2 Struct Op, SAGE, a military defense system, hac 


42) 


” 


nm averzce annual cost of 29 million doil 
operation compared to an srijginal dav 


5S Oo 
rh 


Pissem collars —s 2 |. 
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The neeq for efficient, cost effectisze software wainte- 
Deneces 25 amportant because "....0f the need to kaa DOD 
creal-tine weapon system softwac2 opsratinjy as error frees as 
possibl= and the need td check tha escalating cost 
asscciated with modifying this software" “Raf. 16). 

Gooi documentation is sean as one of the best tools for 
improving software maintenance °“Ref. 19]. In general, docu- 
mentation serves as a means of communication within mn 
ocrjanization, especially over tims. ODodtunentation facili- 
tates the training of new personnel and aids in modification 
or asoftware system by people other than the original 
developnent programmers. Silbay [Ref. 20] sees documenta- 
tion as addressing three prinary groups 2f pecple; nanagers, 
programners/system analysts, a2d users. 43 also argues that 
the software documentation must be cl2arc, comprehensive, 
feted eaard well Structiired in order :> be used effec- 
tively. Good documentation can and must provide a graat deal 


aitceneme2n-OrMat2on. SDeecrfically, this informatisn has “0 
communicate to *he maintenance obversonneal snough ista 

that enhancements and changes t> che software can be easily 
Medgerand GO not DEreduce unwanted erfects in other parts sf 
the system ({Ref. 21]. Table I lis=s examples of th2 types 
MoeeeerrorMatz.on needed in documai tation. 


Docimentation has several important uS¢s beyond 2 
S2heCbail agescription of code. Duting thea software dev2aispmenz 
m 


Simase 22 is used fOr communication between 


2sign téan, for training naw personnel 


4 


m 
qd as 
Peo jvect ard 2S a basis for design reviews. Durkin 
ware Maintenance period the documentation sér 2 
Peet pease, a2 gdiid=> for nodification ini error checking, 
Hemtemoaagan sed coilecti.on of design inforn 


atic S 
Desm@mise! =<{reces DE the ScCitcwara's produstisn and opsration. 


femeeeon -O o=N0ie si Zo Zas PSssSSiz=y of ccneiiering 
= gs sera ton ot pene y pe Wemraceo) =5 ah 1Ategrea: 
pore-on Of the software developmen= process [ Ref. 22}. 
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| a —< 4 
{ TASLE I | 
| Information Documentation Provides | 
| 
| =p SCOr1 Cal pecord of software systen deveiopm2act. 
: | 
| -A detailed analysis of software systen design. | 
| ae . | | 
[ =A wall structured source coie listing with comments | 
Memo or 2g Cc and processing flows. | 
| | 
eehewrarecatvmen, logie¢al, ani physical characteristics | 
|} of the Data Base. | 
| | 
| - Requirements, operating environment, and design 
{| characteristics of the systen. 
| | 
m2 el 2PSehuc=icns fOr no2-AD2 personnel that 
explzinsS what the system (software and hardware) 
does and how +o usé it. 
| | | | 
eeereztat Of input data and output reports. | 
| 
| ice heal information abdut dats; coll2stion | 
{ requirements. | 
| : 
Mee-Perartleqd specifications, d2scriptions, 2nd oroceiures | 
| for 211 tests and test data. | 
| : 
oo See ENS ee ES ED HEED ne ETE SO SED ED ED OD EC ED eat eee oe OD OD ee eee an an ae on amo d 


Peeinmentation 15 an 2mpeorzant “preduct of sound soktware 


Segeenecrsng daesign rather than 2 simole by-vrsiucnz of 


Oes2 gn. Documentation has to b2 clear end soncise. The acocu- 
Meoadceetor Seemat has to be convemient ani simple *9 use. The 
Peecumemeatson has <c be organazed if a hiarchical fashion La 
*h2 sam= manner that the cods is structured. all design 
@eees ons and ‘their impact has to be axplained, and thé 
Bawee@eo ogy =©=j modifications ieciied in advance. Version 


fig@eehe account =ng M22 hocds IOC M242 f2Ccatioa £9 ths 


Q 
O 
33 
+ 
ie 
O 
ew 
~ 
fv 


Bo seWerto, tas 2O be thorough [Rsf. 23 }. 
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How much and what types of documentation must be decided 
during the the design phase of system ievelopment. Yuch 0’ 
often these decisions have besa put off until late in the 
systen development cycle “ise Lesults 2) poor or 
non-existant documentation [Ref. 1}. 

If we are to improve the naaintainability of larye sof<+- 
ware systems we must also "design for change" as Parnas 
suggests (Ref. 24]. This instlaies designing good dosumenta- 
tion to tell us what a softwar2 system do2s and how it does 


i+ 


—_ =~ © 


Be PURPOSE AND ORGANIZATION OF THESIS 


The purpose of this thesis is two-fold. Pirst Lt) geal 
examine and review Federal and Department of Defens2= diréec- 
tives on standards for documentation. Bocisuded wold “oe. 2 
summary of the various techniques of dotimentation from «he 
technical literature. Seconi, a issign f2r a Programmer's 


Maintenance Ménual will be pr2zsented whith incorporates the 


2s 


laztest concepts in software engineering. [he reasons behin 
eee arcactlar design and the bsiefit t>) b= gained will bs 


( 


discussed. 

Chapter II of the thesis will ceview the c 
Software life cycle and how software no 
Mace tO Gicferent lite sycl2 pna C 
Surrent DOD directives in software man2yement that gov 
w2apon system software will be givtn iére. LScan tg Ves 
currently available for pr 
for documentation will be S 
meine gues includ® methods for reoresenting pr 
Such as S2mucewrcd  Progrin 


coOmmentid program listings 
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Chapter IV GORtaInNS a  126CEi prion of a Progoa@pmer's 
Maintenance Manual based on DID requirenents for softwares 
documentation and recommendations for schinges “<3 Such 32 
Manual. The manual is designei from the point of view that 
the program iisting now proviies 2 great dsalor "sslf- 
documentation" resulting frou advances in SEsuctiured 
programming techniques. In adiition th2 purposes ani goals 
of a manual in general are pr2sented with a view that any 
Manual should be designed for its inteniti user. 

Peay, Chapter V will orovide sseslusions ani rescon- 
mendations. An appendix contains a copy of the current DoD 
standard for a program maintan2zace nanual. 





II. BACKGROUND OF SOFTWARE DOCUMENTATION 
A. THE SOFTWARE LIFE-CYCLE 
All software, tactical weapon systan and general data 


processing, must go through sev2ral phases or steps from the 
time a need for a software system is conzsived to the point 
where the system is cperational. This series of steps is 
generally referred to as the softwares life cycle. The 


different phases of the life cycle havs various nanes when 


discuss2?d in the iiterature. Many representations of tha 

mee Cycle are described. PFigice 2.1 depicts ane such qel 

based on the well understooi DOD syst2m life -cycl2 as 

present2d in DOD Instruction 5))0.1. Figare 2.2 represents 2 
mare general approach to the life cycle phases. 

1. Software Development 
in Ordenperos understsanl better whe: nuwse be done tc 
n of each 


create 2 software system, an informal diascriptio 
se 


pha mS provided [Ref. 25}. 
a. System Feasibility and Analysis Phase 
The eventuai user of a syst2en iiscevers a4 nesi 
for which 2 computer based iadgornation system om weapon 
system seems +o be the answer. Bre Netits> of @he aeed is 
Meeeveora: “the outlines of tia tyoe of System thee would 
sa2tisty these needs are estabiishec. [Ths nost feasible and 





| DeeENSE SYSTEM SOFTWARE 
ions CY Ging | bitin els 
MAJOR PHASE SUBPHASE 
me. aie cae (<> “Sees eel | 
{ | R2quiranents 
| Definition 
Conceptual ees Get ee Ge -| 
| | Requirenents 
l | Vee aa con | 
| Validation Valliiation 
a a a oe | — — mw om wee oe ae @ oe @ @ = @ @ 
rPuli-Se¢eale Full-Ssalé | 
Development Develoonent | 
PROd 1CtLON i Die cee 3014) 
me = esa, oO ne = | 
| : | Jebugging 
Depioyment ae ae ae ae ae 
| | Bane Myon 7 
a i ac lla | 
j | Malntenance | 
| SUPport (ar een et 
| | Modes © 2 On | 


Figure 2.1 DOD Software Life CYzl= Model. 
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b. Requirements Specification 


PUNCtLOMa l GESCELpticns of the system ar2= devel- 
SeeagnsUslng @ particuiar formal methodolojyy. Constraints on 
the system's structure and resource usaj2 are identified. 


ECONOMiS constraints cn the davelopment orocess itself are 
° 


stated. This phase may be an iterativa srocess that oscil- 
lates between the statement of specifications and refinement 
ro} 5 


ct the i¢esiaqn. Decumentaticn standard 
T 


Ss 
tives should be defined and listed. This phase i 


d 
ani manageme 
Q S 
EeMEGONSiSely State what the system is t> do - no 


Et. 
c. Product Design Phas2 


Werking from the specsificaii 


1 
h@=sGwers/sottware architecture is conceivei. The underiyiag 
Feeieenc@ Of the problem t9 which this s' 


Ss 
Sour sons SCUgGht Dut. When t41S struccuc2e becomes clea 


Ack 
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Figure 2.2 


will be 


test plan is developed, preferrably by 32: 


(p 


le 


cf 


use, 


needed are created. 


Software Life tycle--Gen2ral Schematic. 


onsnips, tha basic 21 


and the major data re2orese 





d. Detailed Design Phase 


The major parts of the design are now refined 


j- 
J 


detail. Frecise algorithms ani data strictures are defined 
and spelled out. If not already done in the Product Design 
Phase, decisions as to which parts of ths System will be in 
softwar2 and which in hardware are mad2. Both detail design 
and product design may requic= several lavels of refinement 
and reiteration. 


€é. Validation Phase 


+ a check nust 


At this point in the developmen be 
Eales. fulfilis the 


made tc ensure the design, ia all da 


Apecirications 


if 


f. Programming, Cod2 2nd D2bug Phase 


_, of algorizthms and data repressatations 
ms accompliske in this phas2. Pidividual modules ase 
preparei and tested individually. AJ b2Ssae “debugge nage. s 
completed where possible. Sone bugs may adt apoear antil all 


the system parts are executed together 


G. iIntegration/Systéem Testing Ph3iss 


od 


All ccoded modules ire place 


Ai 
peeceminls Gata base. This produces a physic 


mrenrdesign. integration of 32ii the parts, SyYSten Resting 
mecoradsng t> the system test olan, ani 2sriormance evalua- 
e20n 2S accomplished. In many sases a2 yooi deal of redesign 
and fmipmomencact2.On may take olecs at this time t5 force 
Miemcceia: System tc conform <9 the ipscaficayions ane 


initial requirements. 


es 








Everything that happens after the software system is 
finished, deiivered and finally accepts by the usar falls 


a 
miemths Operational half of the life cycls. 
ae Maintenance Phase 


Tauseworthe offers a definition of maintenance 
emeatesratiors to the software during the post isliver 
peticd that do not reguire a ceinitiation of the software 
developnaent cycle" (Ref. 26]. de also views the maintenance 


Pisce 425 any software related activity, principally suppor- 


fave in fort, which keeps the softwars system opsrational 
feeea2n its functional specificaticns. Pie Main ecuivety of 
maintenance programers is corrective in nature, Sommonly 


teferrei to as debugging. Taussworthe considers enhancemen-s 
as essentially changes to ths specifications whith enable 
the software to perform either a new task or a differen= but 
Similar task. imtjeecen —scase Che” Lunseianal seops “of ems 
progtam charges. 
Swanson (Ref. 27} iistinguisaes betwetn thres 
Sas 


types of software maintenance; rtorzsctiv2e asintenancs, 3 


tive maintenance and perfective maintenance. CSEGeectEuys 
maintenance is performed in responss ~9 failures such as thea 
abnormal termination of & program or ths faiiura ¢ts5 nee 
BeteOrmince criteria. AGaptiv2 naéintenzace is pers 


c 
respons= to changes in environments such 32:5 the installa 
of a néw generaticn of system iardware. Perfectiv 
MoanGe 25 perrormed to make the program 3a aod 5 


impiementation. For sxample to improve processing efficiency 


Other authors feel maintenairise has saly twe 
basic components; modisisz31t=ons 224 enhansements. 
SeteeeGat. Cons ar2 any changes *o ekXisting <tunetions 19 





correct bugs and meet specifications. Enhancements are addi- 
Smers Or New functions that wera in th2 sciginal design but 
never inplemented or were adijiei as a rasult of an iteration 
of the development cycle [Raf. 25}. Hodificatisoe and 
enhancenents will be the terms used in this thesis to refer 
to software maintenance. 

A more accurate aad definitive model of the 
Maintenance phase or the software life cyzle a 
cycle itself has been proposai by the Rodn2 Air Development 
Center [Ref. 28]. Pagube s2o3' -2lauses. = Ww 
items concerning this model. The first is that the process 

Vv 


of software development is highly interasti 


Oo l¥portagt 


e (indicated by 
feedback arrows) in order to incorporat2 new requirements 
and changes to software specifications. Sascondly, and more 
importaast, it emphasizes th2 importance of the maintenance 
phase. The model indicates that maintenants phases are *5 go 


m 


0) 
@ 


thocucgh the s iterative steps shown for software develop- 


j4. 
(n 


ae L de 
meant, that 


>: analysis, sp2 


QQ 


GeecatlOn, desumer, codumd, 


Mm 


Mrladation, ~est and integratioa. 


be Decommission Phase 


Duting this phase an assesmel1t SE ene sdicwars 
Memace tO determine its further use, or tembe replicsi in 


Were 26 ©S Gernsidered more ertdnomical =t5 replace the ssit- 
re ther to modify the existing system octwherte procure 


W m 
9 new hardwere dictaes a new software system be developed. 


Be SOFTWARE MANAGEMENT 


Somewane Mahagement is crizicai to che su 
tion of a large software system. The dscisions nad 
managers of weapon svstem softwa 
= 


S 
memeeoepe ween “whether the £inas orsdist is maincacnable 
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or non-naintainable. Cave [Ref. 29] beli2aves that: "Project 
failures are generally the result of improper or inexper:- 


wry _— = 


enced Management and not the lack of tachnical apvility." 


Cave conciudes that the successful 2veziopment of large 
ftware systems can be achisvei in a consistant manner. 


In Tooper's point of viaw { Ref. 30] 2 common stumbling 
block of software projec management has bean that manag2- 
ment would always seek to ootinize the isvelopment process 
in trying tc meet budget and scaedule constraints. This type 
SE @Pproach creates an initial design wita little dotunenta- 
mon cegailtimg in increased difficulty in Maintaining the 
software and @ corresponding intrease in dsverall life cycle 
EoSstS. 

Mitple there is no step by step prostess which wiil guar- 
enzee successful development of maintainable softwars, somé 
general policies nay be stated that are quits helpful. Daly 
(Ref. 31] lists several items taat have oroved useful based 
cn his ¢xperience in managiag software ditvelopments. fT 


Mmummemetdes a listing 9£ two different approaches. Daiey 
iv 


Bscommenads Method 141 in order to produc® a4 cost-2ftective, 
more maintainable software proiuct. H2 also rveccmmends thé 
Soplaeecion of Strict man2j2menrt obdjectives -5) Gtied= 
developnent. 

1. DOD Managemen? Policies 


In December 1974 a D009 Softwar Steering so 
emcees prached with a goal ot identiiyieg ce2tizcal weapon 
System softwere problems and t) ctecommeni oolicies f3c “their 
So ut2o0 . 

To support this committee che MITRE c 


ce) 
Son jwection with John dopkias Universecy {Reet 32,335 
a 13 


conducted a study of weapcn system softwace management. tt 
feseeeecenciuasd «that "...the2 aajor contibuting fastosr <9 
Meeweaecyscen problems is 212 iack 3£ Tec e oa Nese 


BS 
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TABLE ITI 
Software Desijn Methods 


| 
| 
| 
| | 
| | 
| Method 4 Metnod 2 | 
| | 
| High level language Assembly language 
| 
| meeliccured Code Tight conplex Cede | 
| Composite design(hierarchy Garge blobs Of seoa> | 
| of small segments) 
ipe eezallel, mo TSM botton Bottom-up design | 
fee waeeaesign all optimally | 
| used 
Simple data structures and Tight, e2ffecient, daca 
ewer ereas (not) tightly STEUeCUC Ss SNGeawom nae a Si] 
| packed every bit used, no data | 
| Woe cat 24) 
a a | 
{| Team approach to design One prograa-One man | 
| (egoless programming) concept | 
lees Structured walk- NOovdetailedytechntcs. | 
meeesough ror a 09 review of design or cedee | 
| detail design and code 
| aie | 
| Three seperate teams,one Omegamea | coder ests, | 
| design, one teasts, one integrates and neips | 
evaliates evaluat? ALS progrin 
| . : . | 
Meee cmetete Set of hierarchy Detaled 2 Ow gena= = Ss nS 0) 7] 
feecna=-s, Sequence charts general aatcratayes, 15 | 
data maps and narratives, COMS2stsicy £3572 ng | 
well commented listing with comnents | 
| | 
{ Demag toca test plans tor NO -sortal test olans | 
| @€@ii test phases 
| Program maintained by 30% PTogran naintained b 
{| senior pregqrammers inexperienced programmers | 
| OPA ASG i0 beans | 
, | 
lee Onay commercial | BXCenSive NOn-=Cemiacsie | 
{| docunéentation generated technical memorancun | 
{| during development g¢neratei and placei ia | 
LAB aT 
| ® : e e | 
| peeeee sta naegement | NO manag2nent objectives | 
le Obgee ives ¢622611 shed | 
| *£O diide deveiopme nt : 
| 
| | 
| 
| | 
Oe a i rrr ees ees ee err wees ene cane ae emer ae am on on ae am ow ee erent ew areas an ae ae we a ov ee S 





engineering rigor appiied t>3 weapon system acqyuisiticn 
asec ieveties." 

The scftware management steering committee incorpo- 
rated this and other ideas inato a comorzehensive olan <¢9 
miecuud@e policy, practices, prosedurses and tachnolegy initia- 
tives "Ref. 34}. Parts of th plan are intended as 
Supplemants to principles stated in DID ee@ct: ves 5000.7 


and 5000.2. The first maintenance managzmint policy stat? 


WV) 


+hat "Base of maintenance and nodificatiodn will ob 


(Dp 


a majo 


4 


consideration of the initial design." 

Two techniques are used to orovide manaagemen* 
control to weapon system software. Thes2 are design reviews 
and configuration management. 


ae DeSign Reviews 


MZ L-STD-1521 (USAF) annotat]s and describes ths 
requirements for the following technical raviews ani audits 


en COmpPUuceGL programs: 


Systems requirements Revicw (SRR) 

- Systems Design Review (SDR) 

- Preliminary Design Review (2D) 

- Critical Design Review (CDR) 
=eirneaeeonal Confirmation Audit (FCA) 
- Physical Configuration Audit (PrA) 


- Fornal Qualification Review (FQR) 


MecOst*@are maintenance guides 


(oie: ( 5 
eopiptiem=eat =o MEL-STD-1521. Te describes items *o 92 taken 
miaomCouSs  deretion in order t)3 oOptimizs che mainteaiazb_1l-cy 
of software. Wom Spee waver der, Nites. Oo wemy Of Efe: 200s 
fe= Benet 2s crefezred to standac 4d. 


tO 
wl 





be. Configuration Manaj2ment 


Configuration manag2ment consists of configura- 
Eine tacntification, Gontroly Status accounting and 
eid iabaeng . 


As part of the proodsed requiranents assigned to 
contractors for the development of weapd1 system software, 
MIL-STD-1679, Weapon System Softwar Davalopment, staces: 


ieemecONncreetor shali establish and implemenc the 
disciplines of configuration nanagemant; namély configu- 
moe ) 1deitl fication, cote Gea etd Comrie &, aun 
EeuereeyinetcOn Status accountiag. The coitrcactor sn21l1 be 
S@enmezant cl the requirement “for Long-ter iat (Gy.cune 
Support of the weapen, systen softwar2. The approoriats 
degres or configuration management snall be appliad to 
2nsure completely accurate csdrrelation between descri 
tive documentation and th: PCOdram in Ora2e << 
facilitate post-delivery maintenaaice by sofitware Suppor 
personnel. 


a 
Oo 
c 


GCONLIJUratlon ideriatifisation znvolwes spe 
Gai ly @denmtifying and babelingy ‘the configuration it 
selectei baselines during the Softsare its 


Baselines are reference points or plac2ais in the 132 


oO 


ment of 4 system; 


e 
Vv 

a baseline is formally isfined 2t the ena 
ef eech stage in the system Life cycl3s. For e¢xaaol 
aL 


functionel beseline is typically the requirements specsifica- 
Seems document that outiines, in ters both «the buysr and 
developer can understand ana agre2 to, awactlymwna: <= 
System will do. Configuration items are t22 individual enti- 
mse that, together, dertin® and descr@be the basclune. 
Maer. 36 } 

25 the aneans <= 


Come Gears on CONES Ol provi 
Manage changes 79 ~he (software) con 


* 


involves three basic ingrediants: 


e Dosumentation (such 3s adm ise s toLVe nouns and 
Breecee ts <eCnnical ani 2dmMSass ere sve material). Ler 
moMmalily plecipitating aii d¢finiag 2 proposes: changes 
*o a sSort~ware systen. 

men 6 OTJarizeational body £52 Formally eValivieatiag “ga 
aegsoving O= desapproving 1 bes poss2 change? <5 2 SOET- 


were system. 





° Pracedutres For controliwag te aseael chehigss Goo a 
sortware system. 


Software configuration Swiuls | SescOune ng providjeas the 
méchanism for maintaining a record of how the soft 
evolved and where the softwar)? is at any current stag 
implementation. Software configuration auditing provides 2 
means t> determine how well the softwar2 oroduct matches 
associated documentation. [Ref. 36] 


DOD Directive 5)0).29, Manazy2anent of Tomputer 


R2sourc2s in Major Defense Systams, stat2 

Defense system computer r2sources, ineludinag bom 

computer hardware and computer so ftwars 1 Pers pe se — 

fied and treated as configuration itens. 

Macmpmamary Objest.¢e Sf software confizgurat=on 

Managemanc< is the effective Managem2it of a software 
system's life Svc ec sand eS 2 VC vag cola} olpa clive @'Mekcite nt (ol pe 
Meieesgutat.7On is the final forn, 2rreag2asrn* or 2S5ign of 


the software [Ref. 36]. The i 


rd 


MDIC 
Management is that it gives on2 the abiiity «=o manage change 
- 


Guring the development vorecess. Pes DIOGzaAN Malt liesane= 
Meitieat 2s being designed in conjunstion with and as @ part 
oF the software system developn2ant, then L2 Should be placed 
fmdgeretne dascipline c& confizguration nai2zgsment. changes 
in the désiqn and contents of the maint2arance manu2l can be 
matched Of cirece: PA Ked MEO shang esuen SEne ‘sotiWwas = 
Peeeeems This is the irtent of DID Directive 5000.29. 
2. DOD Directives and Staniards 

Petieres 2nd Drocedurss FOE 2aS71iSsi220n Of SBeaDcn 
Pyeom@emesortware are different in most s2spects irom those 
items) DLOCULEANgG automatsi data prssessieg sayuTpmen= 
(ADPE). The distinction made between thas2 two catagories of 
automated systems iS a Sao Cemacsl bemmeoee ne 19650" S3roeks 


fee Public Law 89-306,40, U.S.C. 759). 
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The Office of Management an Buizat (OMB) and the 


General Setvices Administration (GSA) adninister tha Brooks 


Act guidelines. ADE Pi S ecomera led by Ens) Been 201 Sage 
under the cognizance of che Assistant Secretary of 
Defense(Controller). Weapon system softwara, on the other 


hand, is excluded fron the provisions 3€ this Met and fall 
Pet che jurvsdiction of the Jffice of the Under Secretary 
of Defense for Research and Enzyineering. 
Peeceees iS HO centtraliz2d sSsours> of gquideae>s gaa 
2spect to weapon system software maintenance For DOD 
orgaihzations to follew. There 


ray) 


re many directives, reguia- 
tions, specifications and standards that impact on weapon 
26¢ 


system software to varying degre Th 


(p 


NOSst important ones 
ac2 described here. 


a. Weapons Standard WS 8505 


WS 8506 is consider2d +9 bs 1 comprehensive ani 
feayeegaed specification tor the documantion of orzogram 
davelopment, particularly in view of its sarly publication 


wee (io71). One SE its strong points is: 


A strategy for makin 2acth $= lavel oF HOE Cig) 2 
eeeero vo tO (ths next wopec level (subdprogran cae 
under progran des sign) whish represents foresight in 

use of top-down i¢sign prior t5 the tin2 thiS term was 


in vogue { Ref. 151. 


Ze dces not include such programming tacshniques a5 struc- 


tured pregramming, bw this tachnigue was not develop2i az 


eacmieme Of 225 publication. 


It= weaknesses include a itack of chang? proce- 
dures, documentation standaris for jisqranms such as 
Hee seaeny ii[nput/Outpuct or HIP)) tide clgsesston.  tescing 


rkeice 15 j. 


23 





b. MIL-STD-483 (USAF) 


Mee -SiD=46s (USAF) TCOnEzgura=- on Managedent for 


Systems, Equipment, Munitions, and compaterPrograms," 1 Jun 


iD 


Qu 


Ieee; aertines the entire spsstrun of astivites associate 
WMeeeecORtCrTOlIing changes (a4 sritical na2i for maintenance 


work) t) computer programs. 


C. MIL-S-52779 (AD) 


Wee S-S52779 (ADDY, "SOL cwar> Juatery Asstirance 
Program Requirements," 5 April 1974, reqiirces that a Quality 
Assurance Program (QAP) be implemented specifically for the 
developnent of computer prograns and related documentation. 
Even though this standard is concerned with the development 
phase, it important becaus2 it can directly affect che 


is 
quality of software documentation. 


Gas) SSCNAVINS Ge 3500.1 


SZCNAVINST 3560.1, "Hepartasn= of the Navy 
G2ctaica! Digital Systems Documentation Standards," 3 August 
1974, identifies, names and describes that set cf documents 
n2ecessacr d maintenance of 


y to suport both the fTavelopment and 
ware. A review 2 3560.1 was condustec <t09 


ee now wel 


tH 
= 


= 1 this standard supports software mainte- 
@emecec=v_~y [ Ref. 37}. AS noted by this review there are 
€ 


positive and negative aspects +9 ti standari. Some 


cl 


| 
an 


2v2 aspects include: 


- Applicabie document statsmeits. 
- Resosurce budgets (tine,spac2). 
-~ Numerous examples. 

~ Content check lists. 


inet nace Cesc rT_UtLoOr s.« 
V 


fs 5t COtMeemrs £Or f2¢n siscufication. 











The deficiencies of the staniarcd include a lack 
of requirements for the subject of tracsapalaay, «€@ need for 
increas?d emphasis on validatio1, and the use of inconsis- 
canteor non-defined terminology. Ihe raviaw indicates tke 
standard seems more orientated towards software development 
then to softwre maintenance. Tha review also notes the stan- 
dard's strong orientatior towards the Vary's tactical data 
SyStem. Scneidewind, [Ref. 37], recommends "...2a more 


general orientation might be preferabl2 to achieve a wider 


applicability to a variety of software systans." 
Se DED” DERECTIVE 5000.29 


DOD DERZCTIVE 5000.29, “Management of Computer 
Pesourcss in Major Defense Systams," 26 April 1976, estah- 
lishes DOD policy for the management 2nd tontrol of rzomputer 
resources during system acquisition. lel Mies 0 a Diy) aetyee De 
software is called owt as a2 major consiisration ducing the 
initial design. It also directs that supsort items required 
for cost erfective maintenanc= be specifiei as deliverable 
items. Documentation is listed and defined aS 2 suppor: 


item. 
ies MT L-STD-1521 (USAF) 


MIL“-STD-1521 (OSAF) , UTechaical RevicwS amd 
Audits for System, Equipment and Computer Programs," 1 J 


u 
wove, DSESCr bes the requiramsats for tae conduct of tech- 


Seeds vewS and audits in conjunction with the dJosumsnts 


4 


peecdmene MEL—-STD—-483. Direction is provided cenceraing tas 


mewerna dudit Of Computer program COOofi guration tten 


wD 
Oo <q rr 


S 
mines sOCiated documentation. Each *yos 3£ review or audit 
Vv 


*s described in an appendix to the staniacd and can serve as 
@ pasis Zona Checking <comoLt ance with maintainability 
requirenents. The documentation discussaji here is rei2te|ec 
more toward system desiga reviews ‘thin *owards ite 
femcwitem=ac.On OL Progtam iisting s. 





g. DODINST 5000. 31 


DOD INStrc ust ion 5090.31... "£9 See ea Least. of DOD 
Approved High Order Programming Lang 
November 1976, specifies whith HOL's ars 


2s HOt), 28 
GOved £OC Use 10 
eongunccion with DOD Directive 5900.29. Although this 


instruction allows for certain exceptions, it atteapts to 


wm W 


reduce the proliferation of HIL's in is2fense systems by 
limiting new development to six approved languages: CuS-2, 
See, LACPOL, JOVIAL, COBOL, and FORTRAN. Its Major impact 
Moan the standardization of compilers ard in preventing 
each DoD activity from developing its own unique programming 
languag2. 


PLL OTD = 67 Sed NAve) 


NEL=SED= 0/9 (NAVY), “Woapo1 System Ss dftwars 
Development," 1 December 1973, establish:s uniform réequire- 
mMenes ctor the development of weapon syst2m softwar within 
De otcact adherence to the provisions of ‘this standar 
Mmeemenerp ensure that the tactical software so dsveloped 
Moti be improved over current varsions sf tactical softwares. 
MIL-STD-1679 includes developments in oroqgza 
nology, and management such as Structiurei progranning and 

h 


design walkthroughs, which hav2 occured siace the release of 


nee 8 506. It stipulates the us2 of high srier languages and 
Specifies the use Pee Onte FUCA COON eiNaAnate Ment Gob “cConre= 
Meseng documentation with ithe progr2n for maintenance 


purpeses. fRef. 15] 





III. TECHNIQUES TO SUPPORT SOFTWARE DOCUMENTATION 


A. STRUCTURED PROGRA MMING 


There are several definitions and goals of structured 
programming. Some of these goals relate to the design and 
testing of large software systems. Ons osarticualr goal of 
structured programming is to organize and discipline the 
program design and coding process in order to reduce logic 
type errors [Ref. 38]. It is generally accepted that the 
Goals of tructured programming incluis those of software 
engineering. In particular these goals ar2: modifiability, 
efficiency, Seltabsi2ty, and understandibility of the 
program code [Ref. 39}. 

What must be shown Ls how strustured progranming 
Supports documentation. This is not 3asy to do because 
structured programming is not 32 universal and well defined 
Concept. It is defined in many places, (ref. 39,40,42)], but 
no* aiways consistantly. Howaveir, its 2ss2nce is faicly weil 
Mma@erscood. It is the practite or of programming using 2 
meteereaeouct Sufficient set of sontrol constructs Figures 3.1 
Mode S.2 illustrate the five basis control construsts as 
Beguire, by MIL-STD-1679. 

Myers [{Ref. 18] provides a list of seven basic sien 
of a structured program which should b= apolied <9 

Heemonoglzeam complexity and oromote clarity of though b 


re 
che programmer. 


to 
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Myer GMa H FT O 


code is ccenstructei from s2quences of basic 
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el. Variable. amss,  avOL 
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code is properly end=nged on 
KS execution ssqusncee can 9 
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Sequence If-Tien-zlse | 
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Figure 3.1 Bastenwconeceol Goistruces. 
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a DO statement can be easily matched with the 
Ao O statement ending th2-loop). 4 

e There is only one point of entry ani one point of exit 
in the code Soe Baa modules. y : 

e The code is pep ioncat ly s Se diteneed)  O) tnome scin ng | 
enhance readib: axecutabls> statements or 
moijule should fit on a single page Of She =l2Seng. 

e phe code represents a sinple and straightforward solu- 


Zon to the problen. 
Figure 3.3 provides an example of structured and anstruc- 
maced coding. A StEuUCtUbed progaam is StEUCEUre) pine yo 


Beeeecrsi. WayS. First, it is structured with regard to flow 


uv} 


Memeomrco Ol and execution of the progpan. Second, 
paysically szructured by the us2 of indentation. 
Another way of viewing strustured programming is to 
MemcdcecnOSe attributes of a program that contribute to the 
GBeadupalty of its forn. For 2xample coisider the jievelop 
Ment of a file management system. Obviously one required 
mametson Of stich a system would be the capability to. search 
@oeeca given file identitied by a specifics name. Figure 3.4 
illustrates such a function 2s coded in th? recently devel- 
oped DOD high order language ADJA (see *;REf. 4 
on the ADA lLaénguage). AS Gln (be s=ea 2a Figure 324 Ste 
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begin-end groupings which anake it easter to follow tks 
Peogsem flow. Comments are auséd 2x zensiviy to iatroducs 
each new module and structurs. 

Deeweestits Of Structured oOrogr 
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Tent with easy +0 read code ani 2asy 


miwertrens and procedures are confined ts iiscrete areas in 
miewproitam i2sting. Th= cbjective is 25 nake the code, in a 
Vv SSumMenNT 6g, Lads 


Sventcenangrul and useful way, selr-} 
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Figure 3.3 St nuctured vs. Unstructured Coding. 


This has an esffect on the design of the document 


called the Prcgram Maintenance 4Wanual ani will be discussed 


code. 


Poeec@e=aii =n Chapter IV. 
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funct20n SEARCH (FILE _NAME;KEY TYDE)ceturn 

FILE_INDEX is i. 

begia | 
| 
| 
| 
| 
| 
| 
| 


-- Look for the specifiel Key recori in the 
peomcipec= fled Elite, neturting the itniex of its 
=~ Pese tion 
Bom l in FILE _ INDEX *FLRSTS.PILE IND&xX*LASI loop 
=~ a the wholes data base, From first to 
=~ las 
if FILE_MAP(I) /= NULL 
a= (neck gata base £or a null or.a 
=- Weaech 
and then -eee = FILE NAME 
aod stnen seis Keyan) = KEY Tyee chon | 
return (I); | 
ene: 11; | 
end loop; | 
Patce BAD FILE; : | 
~~ Rais? an exception if the desired record | 


-- iS not found 
end SEARCH; 


SS ee ee ee ee 
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are ceeeiessimes aes eucteiasees comms axvenmss siiah- oumicien aumincipms dhs au @ve aus = a Se SS Se ee Oe ee SS 
Figure 3.4 File Search Function. 

Be MODU LARIZATION 

Medaies are the building blezks of softwares. Sood 
modular prearammin Sta ely ere q Ue ress -enhie Ssxcernal ine es- 
maces, Sie aS© InDUE/OUuEput, be! Ssdslated into s2penars 
modules. Weewlar PECcgrammang ZeSsl= is «th praceice of 
implementing software in snail, PWeSset oral] y Tentated 


ona 
pieces. These pieces are usually implemenzr2a as subroutinss, 


Mimece. Ons Or clusters Sf Functions. Bach module is devoted 
memmcreror Mere tasks related 5 a functis2; <j~he nodule may 


m 
b2 accassed from one or sStvetal plates in the software 
system. 

Memuerca=ty is oftcn detinel in terms of properties poss- 


essed by "modular" systems. 


A prog=am is medular if 1 {5 Writtse iG Many rFeistively 
*ndep2naden= parts cr moculss wnich have well ijdarinse 





interfaces such that each nodule makes xno assumptions 
about, the operation of other noe We except what is 
eomcarmed irM@the interfete so2cificatisas. 


Meaubarization consists of dividin rogram into 
Subprograms (modules) which san be c niles separ rately, 
but which have connections with other Sorlesa i he 

the 


Nic On ene —' as0dlt Bese must emphasize 
requirement that modul¢s be as disjoint 2s possibi=2 


Modular ,programming is the organiziny cf a couplete 
program into a numbér of small inits...where thete vs 2 


Ser On LULES Which contfols the charast2ristics of these 
2vents. 


Modularity ceals with how tha structu 


Co.098 an @bgect eau 
make the attainment of some po Bac 2asler. Modularity 
Ls purposeful structuring [ R2 

There is a trend towards definin modules in terms of the 


rumber 2£ lines of code they contain. Prozramming standards 
frequently contain a somewhat negative approach such as 
Weeremodules shall contain less than XK lianss of code." Som: 
mienors feel that the size aspect is not 3s important to 4a 
module as its functional aspect. In other words 2 smail 
Blepeex module may be more dif€ficuit t9 understand than 4 
large well structured module. However, the majority still 
favor limiting module size, wh2n possible, ‘+o less than 100 
MepeceoGte code in order to maintain nddiles as “discrete” 
eptities and to aid ceomprehension (Ref. 339,40]. 

Theré are many advantages tO using nodules. Parnas 
meee 28 | argues that the most impertant aspect of nodulari- 
[meee the ability tc anticipate ani dssign fer shanges 
If the function of a modul2 changes, that module alone tas 


1 


t2 change. mo “hewe need £06 2 @Weeeci on Seisss ducing “ne 


- 


feeeor ohase, a nodule with tais functioa cs He aavowed sae 


7 


can 
Memereet er teed, If an error in tne program is f5und, ihe 


Meera y 2s that its correstion will be limited ‘<o one 
module. Once a module has been tested, iad can be coapilied 
eigemeee ly, ot Cah be reliably us2d ia different olaces £na 
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Sinte medularization makes the 


Structure of 3 program@ 
easier to understand while losalizeas Guneedions and 
processes, the need for external docunentation is again 
reduced. 

As a final nots, ther2 has to b2 a distinction nade 


between modualrity and structured progranning. 


This listinction is necessary beraus2? program structure 
is a relatively meaningless soncept in some programming 
mamgMages, Such 32S plain viailla assembiy language (25 
eo tO assembler erhanc3i with sttong macro capa 
De ty). PMmcouel as ti modularity is usable,in all 
domains. Thus, the line between modularity and structure 
Mey be a tenuous one tc walk, but 1 15 an importante 
one. Note that good modul2s nay Or may adt possess good 
program stxcucture and that bai modules nay also possess 

Doe Pasar Structure. The two subjests are discernable 

ef. . 


OF DATA STRUCTURE 


In some programming languages thare are at l3ast two 
MeIoemwOUKIng With a string 2£ bits or chatacters. Jne way 
Memrvomd@scilare the string as pact of a striatture (Figac2 3.5) 


and then manipulate the string oy name: 
OTHER STRING = CHANGE ER STRING 


a EEE ee ee Ee EE ae Se a ee a ee ea ee oA i be ae ME Se eS oe ae ee en ee ee ee i 


Sat 


eeeele cure DATA STRUCTURE, bezyin | 
| foom, Con AC UE Sb N Geo emer a ot SES; 
| feo Orlr AR VARTAGL.. 32) 02tc; | 
| Sd STrUuceUrs ; | 
| 
| | 
| 
| 
re ee ec ee eee ee SS ST Se A SE De me a ee ee ee ee oe = —— J 
Figure 3.5 Exampl>s of a Data Structure. 
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A second metnod is to use 4 byte manipulating funstion <o 
define the desired string at avery point of usage in the 
program: 


OTHER STRING = BYTE (CHARACTER_SIRING, 5) 


Suppose the character string named OTHER_STRING is utilized 
100 times ir the progran. Lip eordereto change Sehe string 
Eyemat &sing the first méthod (Pigure 3.51, only on2 easily 
Biemersred Wane ft code has t> chafge. In the second case 
emeee ere 100 lines to change throughout the program. 
Languages may or may not support such data structuring. 
Meeer and PL/I provide elaborets® data strictures for forna+t- 
mimemaqmreport data for printout. In addition such changes as 
Seeappinc off leading zeros, inserting 2 decimal point, 
adding sneck pretect charactsrcs, and iiserting a leading 
dollar sign are easily accomplishei. At the other saxtreme 
FORTRAN and BASIC offer no data structure ca 
the array [Ref. 43]. 


Data StrUcture imvtacts the 1reas cf sof 
|g 


pDabilaty beyond 


W 
software maintenance. Ine methodology, cs2lled the ja 
sthod “Ref. 45], stresses d2signing th2 progra 
Cc 


meas LOCKing at the data s*tructur3s. A 


a oOo 8 


meoote an algorithmic structure is highly relat 


ts 


5 

mierusecs  PLlOgramS that obey data strusture design wiil 
ave a more maintainable oroaram structure 25 weil. 
Obviously different application areas hav2 ditterent levels 
Beemeed £Or data structure orlantation. 

One of tne noticabie eriects of larj= software systens 
Memenae eigoricthins end up traastormang »n= data 
AMeomagooher Gata structure. [his resuits in ‘wh 
€5rmS ae "structure clash." The reason for this c 

monly a proliferation ci unnecessa k 
Biwed programming goals, or iask 3f n 
a 


Welibash'. 43s a mesylt OL  MALntenen 


a) 





enhancemert, where the changes have adisd information or 
changed the cata structure to meet th2 turrent ne2i. Two 
Sdlutions have been proposed in this area. GEsuping or 
"clustering" of data and abstract data tyoing [Ref. 43, 49}. 

Where a set of data declarations intarcrelate, either bv 
function er by context, they should be grouped together for 
ease of understanding and modification int s one biock. This 
Bomemes! clustering" ccncept. If a chang is needed it can b= 
isolated into one block. Only those modales which ase that 
block of data need be recompilei. 

With the concept of abstrast data tyaing, such as used 
by PASCAL and ADA, (Ref. 4&8) all data nust be explicitly 








Hectared to be of a particular type. Clebeaer tvpss. S22 
defined in the language, but these must b2 supplemented by 
programuer-defined types. Associated with 2 type is a set of 
cc . nS] cite eet ca eae a eS Se er ee can | 
' | 
: | 
| | 
| EYpe RECORD TORMAT 1 is 
record 
| Seo) Manat: sereay(as.30) of CHARACTER: | 
| FMPLOYEB RATE: float; 
| DUC LOY semmOurRS: imeeaqer sagqs 70... 99; | 
| FILE1_RECORD: RECORD FORMAT 1 | 
| | 
| 
ioe ES eee et _ 
Figure 3.6 Example of an ADA Data Structur:. 


legitimate values which cbjects of a type a 
Pelee OUetcet2 ONS which May De psSrisrnsad On chat typos. 
Pee eS 4-5 end 3.6 Show examples of ADA lata structures. 
Dhrse kKird of “yDing has thrse charast cS ( 

of a 


é Ss 
properties typ are defined ceatrc2lliy et the Fyss 
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Mei@iieretecr, end if they changes they nesi only be charged in 


Smemwples>- (Zz) only the absttact properties of a2 type ses 
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De known to reference data of that type, with implementation 
details "hidden" in the declaration; ani (3) strong type 
matching may be enforced by +42 compiler, eliminating type 
mismatch errors as 2 reriability/mainatainability issue 
f[Ref. 43,44]. 

As 2 final consideration, it is always important to name 
data effectively. Meaningful names ar2 aiways preferable 
EMPLOYEE_NAME conveys far mora information about the data 
value then EMPNAM. This supports tke goal of readability and 
the uitimate go2l of having she program be as self 
documenting as possible. 


D. DATA COMMUNICATION 


There are two basic types 2£ data comnunication, i 


- 
_— 


? 

‘ 

t{ 

jv 
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program and inter-program. [ntra-program data commuaicat 


iJ 


t te 


mM 
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ie ee 
wD 


is essentially communication between modiilss. This c 


accomplished by paramenter lists, global (or common} 


Qs 
e) 
qt 
jv 


wma sSeen= concept called a iata "cluster". A cluster : 


(N 


where a constrained "samiglobal* data bass is shar2zi amorg 2 


memaeem number of processes or Functions. {fRefr. 42,43,44 ] 


A paramete= list identifies only those data items and 
formal parameters used by ach indivijiu2l snodul3 The 
Meoterced method of intra=projrcam comnuiication is by the 


use of a parameter list [Ref. 43]. rhe main 2dvantage 
gained is that all data used by the module are ijantirtied 
ani isolated. I= is not possiole for tha nodule 29 have a 


me 
Seeeperse effect on the code Which invokes ths moduls. 

Glooal variables ar= used for largs quantities orf date 
Wher it is not convenient to speciry suca a la 
peemmeae; POLnt of cali. Yost authors rece 

Weewor Global data £52 good nodawleas 24 
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iQ 
ct 
pal 
(iD 


mi 
Zz G 
programs. The reason for limited use 15 thet a module may 
m2 C 


Mmeaveematobal value whose Sti ginai valio was criti 





the calling environment. This may lead t> undesirable and 
untracable side effects. [Ref. 40,42] 


A side effect is one brought about oth 
parameter mechanism. It 1S Jeneraliy son 
undesirable to writ¢ subprograms, especiz 


r. than via a 
Sidered cacher 
- Ply sins 10 aS., 
which have side effects. How3vet, soma side effects are 
Beneficial. Any subpro ran which performs apie — -Jutput 


Paks w J (D 


has a side effect on ke £lle; a_ fFuastion delivering 
Successive numbers of a sequ2ic2 of random numbers only 
works because of its side effacts; if on2 needs *9 tountr 
how many times a function is Sloe then we use a side 
affect; and so on. Care must be taken when using cunc- 
<ions with Side effects that the Function does not cause 


SeELOrs in other sections of tas progran. [Ref. 44] 


mie cluster corcept is an attempt t> fulfill “the need 
fot global variables. A dat32 osase and its family of manipu- 
lating procedures is isolated from the rast of the progran. 
A program nééding some or all of of the slustered dat2 must 
Seammeertcaiy import it. The cluster ftself can distinguish 
between data and procedures which may b> ®xported or i20t. 
The side efzect problem is at least isslated and pounced. 
(Ref. 40,42] 


Inter-pregram data communication is orovided either by 
passing dat flags and blocks th#oiignh 331 Gierating systen 
Bemmmiligecantsen area, or by passiiag l2tgec volumes of 1atorma- 
mone, Of files. The UNIX concept of "pipes" in “sn #e€h 


Bec@ec ned files are automatically passei from ons progrtaa 
zt. 06htthe next is an ¢xampi2 of chis tyve Bie 
communication. [Ref. 47] 

Bem osoper use of data communication clarifies progEaa 


meoweand traceability of _— Phes, Si iemese, Supeeees 


“h2 maintenance programmer SAS en oe. COLE Stl. On. oe 
BEOGram erzors andin his theca tale st the oFfocqeaa's 


escmmentation. 
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E. HIGH ORDER LANGUAGES (HOL'S) 


High order languages are those computer languages which 


> 


Hee €ssentialiy machine (hardware) independent. This is in 
contrast to assembly languages that were designed for 3 
particular hardware architecture. For 2x2ample, th2 INTEL 
8080 assembly instruction set will not work at all on 43 
Motorola 6800 based machine. Ina contrast a standard FORTRAN 
program can easily be used on any computer with an appro- 
piate FORTRAN compiler. 

High order languages tend to support the concepts just 
discussed (structured programming, modularity, data struc- 
ture, etc.) to varying degrees. FIRTRAN offers moiularity, 
but is limited for program structuring and has almost ne 
capabilty tor data structuring. COBOL has excellent, robus- 
capabilities for data structuras. Other languages have theizc 
eeeengearnd week pcints. [Ref. 43] Examples of good d2L code 
may be Found in several referenses “Ref. 40,42]. 

Documentation ils supportei by High Order Il3ndquagces 
obey 2t che language is readable. FOIRIRAN is lia 
this respect because of its six charactar limit on iata 
variabi2 names. Some dHOL's, APL for exanple, provide nc 
moicieineyy at all. APL is very iifficult t5 understand 
meas wWertten down, even by the person who designed tha 
program. 

ADA, the new programming language developed by the 

e 


Department of Defense, promises t> offer th bes] Siupocse 


ity 
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just about all the major softwar 2n 
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Wrerereyen issues. Some Of the Kay goals of 

e III (Ref. 44]. 

The overall objective of th2 Dep 
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recognized that professional projrams are r2ad 
fcen then they are written. It is important, 
ore, tO avoid an over-terss notation such a5 


iA ct BH ty 
ts i ro O ct 
1’ {0d On 

lO © HOt 

{= Oo WU 

ID 


tJ 


at each object has a clearly define 

S and prevents sonfusion between logically 
distinct concepts. As_@ cons2quence many errors 2r3 
Beeeo cea by the compiler whish in othec languages 
would have led to an executable but insorrect program. 
PROGRAMMING-IN-THE-LARGE 
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for encapsulatioa, seperate compilati 
Manage Ment abe Nscessary £95 She wre 
a aintainadls programs 3f any siz 
TAN 


Memeo fec. Of lifts that progqrans of sonsegquence 

are rareiy correct. It is hasessary to provide a 

means whereby a program can de construrt)]d in 3 

layered and partitioned ee So that t21sequences 
a 


of errors in one part can contained. 


ieee por wability 2 Matta iia OL te eyes an Done b earn od 
meme Cote l lS Of ths [TSepressentation 32 data can be 
kept seperate frem the specification of the legisal 
operations on the data. 


TASK NG 


tJ 
| 
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Pom many appiications it is important chat «he 
Peodeem be Conce:ved 4s a series of parailel 
GeemeTet2eS rather than just 3s a singls, sequence 
weecemenons. Burlding eppropiate facsi:tlss Bats a 
language cther than oe Sem .ONawees wee lS to 349 
Sieewerng SYStsm gives bettsr portabilicy and 
memes O21 LLty. 

GENERIC UNITS 

In many cases the lcgic of part of a program is 
independent of the types of values being mani pulaced. 
AVheschantsm is thererore necessary tof £n2 creation 
Or r2ieted pieces cf Pa from 2 siagl?2 ctempli2ts. 
ies 2S ee oe useful for the creation of 
iZDEATIies. 
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benefits by reducing the number of differant types of compi- 
ders needed. It also promotes familiarity by programmers and 
maintenance programmers. Improved prograa clarity and read- 
ability should also simplify the documentation. [Ref. 46] 


F. THE PROGRAM LISTING 


If the overall goai is to reduse tha quantity and cost 
Beeecocecumentat:on ani improv2 its quaiity and usefulness zo 
the maintenance programmer, than it is highly desirabie that 
programs be made as selif-docunanting as 295ssible. net bes 
Manner one can substantially reduces the nacessity tod main- 
tain multiple forms of documentation representing the same 
Megic. Many authors advocat= such an approach through 
structured, well commented prcogram listinys. Myers [Ref. 18] 


States: 


Since we aiready have the soi3, dhy not let it serve as 
Eme Logic documentation?... additional documentation 
ellen, aS a .flowchart would be undesirable because i+ 
would be redundent with the code. Reduniancy in any ctype 
of documentation Ssh cuid be avoided becaus? 1+ increases 
Pree cCaanees or conflicts. Furthermore, unless care is 
caken pemiececs sre docimen <3. >on (Wi-oh iS mores itfai- 
sult if the logic documentation is physically seperated 
from the code), _redundent idcumantation cften becomes 
totally useless after the roi2 is modified a few ~imes. 


Giass [Ref. 43] also agrees with this point of view stating: 
ee oilers cs, wnen they d> em2s-, ate generally weiteee 
Mmmcemeaonrm tO a SSpelat>, Set of fcsjutremer=s which 
eceey What =he scf ware documentation i:s +0 edataic. 
All «00 frequantly, these requiransits previda for 
Meselsven= cr useiéss Snformation that che maintains 
Mommie =cs. SO, in amtcal sense, <n iacument, waica 
Mmemenoecsea -O De 2 _Clablivying piece of materiat, e2nds 
Gpweobscur:cg the needed infocaation. 

Because documentation, is_stperate from the software 

mote cmm@rescli, @£t 18 also E£FrSqusntivy out_of date. 
ey mee JOCHMIEN= WOUlde 9 3 P2rlsstensetl<ceticsen st 
miemorogram. in actual fast, yl S as 220s, sk ser, 
emue, The accumentation can therfore 52, nisleading. whe 
Meer fright mind would act2mpt to maxkS COESeCtsons <9 
weepeetwam) ai er teading only the progran documentatior 
Seema e she 12s ting ? 





This ayn OT recommends the heresy 


that the  Lastaing be 
the Ges S where most softwarea documentation 1] placed. 
Near every requirement for documantation describing a 
Program can be met and in fact exceeded by requiring the 


Same information in the listing. 


DOD, in general, supports this point of view and gives 
explicit direction for what constitutes a well conmented 
program listing in MIL-STD-1579. Howevec, MIL~SID-1679, 
SECNAVINST 3560.1 and other directives require extensive 
detailed, external documentation (i.e., other than the 
program listing) +~9 ke produc2i. IJne valid reason for this 
requirenent is the need fo2 extensive design reviews 
required by configuration management tecaniques. A second 
reason is that, until the nid-1370's and the advent of 
sofware engineering techniques 1s discusszi in this chapter, 
the program iisting did net convey a gr23% deal of inforna- 
eeemw. A Large amount of English text was needed to explain 
the design and structure of ths software and its associated 
data bases. Even Giass admits that soma 2xternal documenta- 
tion will always be required to jive 2n overview sf the 
Structure and the software's design nistocy [ Ref. 43]. 

iieaomerexconrmal™ documentation iS ained at specific 
users. Jperator's Manuals ara neant to be read by oo0srators. 
Seer tacat ions are Weant to be read by both custo S: (26 
feape ciom the ability to detacmine that the problem beiag 
solved is the one they want solv 
documents are meant to be reai by custouars, to datermins 


Saat proper reliabilze techaiqus 
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Se-ame rie Bain prcblem assotiaced wich sxternal iscumen- 
Meeeene ss taet it frequently besomes Lhacturate and 3ut Gated 
aintenance programmers m2k2= changes t> the pregraa co 
FOr this reason maintenance proqrammers tend to relay more 

J 


Bydmemot> Of whe vrcgqram Liisting as the saftware system 
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mae slisting i f Of necessity, accurate,. since 2t isthe 
program in ali real senses 9€ the wori. For tke same 
Treason at is complete. Thus the oaly accurat2 ane 
mirerelwcGePaesentation Of a DECQL ams. in today's tech- 
momegy, is trequenily the progrém listing...If we" code 
ES Cc eee Seca much One tke y tira whee docu lenta= 
£ Om wi 1 be also. In addition, the 2xplanations in the 
listing will aiso iikaly t> be readabl2 by the intended 
target audience, a programm2r. They ral also be in 
place where he needs most to Find them. Ihe accuracy and 
eempleteness attributes Of tha listing wiil also tand to 
apply as well to the documantation. ;R3f. 43] 


The main line of thought b2ing developed is that recent 
trends in programming technology, as oresented in this 
chapter, have shifted the emphasis of programming dotumenta- 
maom itbem "“external™ documeats to the program listing 
itself. A greater detaii and quantity of information abdout 
the program is now directly avaiiable ‘+s the maintenance 
programmer. This haga Significant inp2ct on the way one 
should design documentation as a whols. Chapter IV will 
Pesess <his point of view as it applies to a specific docu- 
ment, the Programmer's Maintenance fanual, and how it should 


be designed. 
1. Commenting 


-—_: 
= = 


Tt has bean stated that one objective to improve the 


documentation of software was ‘*o0 make *he program code 
Ztself nore readable. Two technigues alr3saiy discusseda were 
Peeterusead programming and the 1se of high order ianguages. 
Meee so techi:- que is the placing of comaentsS at appropiace 
places within the program code. On2 of ths main aivantages 


SuemGons. Start cOMMenting policy -S its in 
she programming language used. There 4 V 
thaz do rot allow comments #3 be placed in «he Listing 
{Ref. 40 }j. 

Mec“ cond advantage is 2ka= commencing closes ihe gaa 
between computing managers ani computer orogrammers. [his 


peeeedev> Op] because Of the progtemmex's 2bsolute a2324 
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eee oon +O details. These iatails incluie such items as 
assembly ianguage instruction choices, high order language 
statement type choices, flag initialization procedur2s, and 
the design of nested loops with if..thaa constructs which 
implement the logic of the software syst2n. The manager, on 
the other hand, must keep a "Biy-Picturs" perspective of the 
system and be able to evaluate an alusive entity called 
software quality. Software quality is often based on itens 
Such as reliabilty, readability and portablity [Ref. 38]. 
In order to evaluate all these "-ilities", the manager must 
be able to read the program listing ind understand the 
implementation of the software design without necessarily 
Pewee tage er With ali the in's and out's of a particular 
program language. 

Comments assist in putting nore i 
the program iisting as well as making ch? program more zead- 
ible. Comments explain detaiis abour th program that are 
not app2arent fron the code its2lf. Taple IV 
9€ where comments snould appear in th program. 9n2 DOD 
Seo VLC , the Marine Corp's Tactical Systems Support 
Beeweey, nas had a great d2al of sustess in easing it 
burdén >= sceftware maintenanc2 by implenenting & istailed 
Semamenti ng policy. Although ASTSSA's programs are mainly 
Weeeecen 2n the Navy's CMS~-2 languages, it was found “a3 


t 
@ policy helived reduce the amoint of tims spent by progrea- 


Mesenen  sottware changes in aidition +¢5 the tims savings 
SeheeWesl by the use of a hign order languags. [{Ref. 48] 
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TABLE IV 
Recommended Locations for Conamants 


1. At the beginnning of 3ath eats? inzlude the 
module name, the current date, e nodule'ts |. 
PUmGeoOn, 1 ifs inputs ani outputs, Lts limitations 
and restric EPONS, “ancl l ha Se al ead i its 

Heese PiCgae: 2s ane the name Fhe developer. 
Major. moc dules shou also ae Cae the history 
Senederi.cati ons: For 22ch chang2, the date, 
the mé aintainer's name, prupose Sf tha change 


2na sccpe 


2. At each subfunction, whather it b2 a straight 
meaguene@e,ot code of a tagic branch 395£ a begin- 
See DLOCK, angexplanatiosa of that subfunczion. 


Baa cecach interface, a clear dafinitionm of the 
Interface and a referenss for further inftor- 
Naticn about the other side of the interface 
(where possible). 


Pe Sach group of Eunctisirally or Ssth2 
related declarations, 22 explanation 
role and makeup of ae 7 Peup. 


= 


rwise 
of zhe 


peereecach declaration, an explanatioa df the role 
of the item ecg he M2aning, Lf any, Of LES 
possibie values 


Gemeee cach di ae ee gt hope coke) at 5 
an expe anation of what the code 25 and why 2 
scmpiex solution was 2ectessary. 


[ea Saran ay ee 
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a i a ti a 


Ae OBJECTIVES OF A MAINTENANCE MANJ AL 


In order to determine how a progranner's maintenance 
manual should be organized it will be helpful to 2xamine 


some specific goals that apply to any typ2> of manual. 


1. Generel 


bh 
ry 
iD 


First objective is to enunerate those general 
Begatie@it>Onal qualities of writing and style that lead to 
sase of use and readibility of technical pubiications and 
aqocuments. There are several factors that insure tha infor- 
mation contained in 2 manual are is 2asy +9 use. Thess 
Pe 2Of= car be Characterized into two bro24d areas. The firs+ 


mecmcONnceEnS the concept that all infotnation vwres 


(v 
res 
at 
fis 
oF 
he 


em= Manuel be easy *o find or Locate. The second area 
Semcepte that, once ore finds the information, the 
mon 1S ~Teacdi_y understocd. 


fre LFectors that support ease in finding information 


§) 


me CGONRSIScEnCYy, pointers and acrangement [Ref. 50]. 
Memetss2=fcy .s the principle: that “Similar object= (i.e. 


Maintenance manuals) containing the same information (how to 


understand and change 2 computer progran) be presented in 
Saeco cal ways. Dns eines suo sis all nanuals should have 


[m=nt.ci! tormaes. Readers Of the wmarual know what <0 
mpeer ew now =O look Tor Specitic intopmation and where they 
a 


iD 


[stn ce. 6FOr 6a UProgram€6 «6NaaNtenance Ranweal Ze would 5 
helptul that details on data structures b= in the sane 1loca- 
ion in each section ci the nanual. 


s4 





Pointers are essential signposts which identify 


i 


elated groups of information. Pointers are represanted by 


) 


e 


( 


eeeecees SWeh as tables of contents, iilexes ani section 


meraangs Of text. Pointers anadunce the presence and loca- 


Seem OL AinfOrmation within the body of th2 manual. 


tr 


Arrangement refers to the mannar of presentation 
used thrcughout the manual. The arrangensit anticipates ways 
moe which reeders might look foc specific information. The 
subject of a manual might typically be arranged by alphebert- 
Meet Of chicnological order. Sub qect classi f2emri on 


_~ 
1 ¢& 
—_ = 


(D 


another method. For a program mainte2ance manual, oh 
arrangement might be elated £9 the hierarchical d2sign o 


O th 


Poe Mein functions and subruictions o£ the progran of 


ct 


on 


eeime external criteria. This criteria coald be specified by 
documentation standards incorporatsd in jiractives. 

The factors that support ease of understanding ars 
acturainess [Ret s “3040 


er should use 32 voc2bDu- 


Ss 
Sem Le CLLy , concreteness and n 
Pe mepeecrcy 2S the concept that 3 “writ 


lary and writing style that suits the intended readers. 


Admittediy, cne assumes that any paricular person having the 
Meed <> read a maintenance nanual can understand f2irly 

memeiex COmpcsi;tions. Still, the goal of Simplicity is to 
k2ep the technical "verbage" t> a minimun, while oresenting 
ee easena iogicel flow of iescriptiv2= iniormation. Tn 


mire One a Glctionery or aposndax shoi1ld be insluded =o 


oe 
Q) 


Prope yecerten tions of any “buzzwords" for clarification and 


consistancy. 


Concreteness ansures that verbal descriptions 3:3 
More spacitic than general. It aiso iaplies that seg 
‘weacddeats and pictures be provided £55 amplification ane 


Mb see gO), § Cr PLCGIeM NMSLIESnance aaiaszils the besct “ype 

© diaigsams <c use has seen a long history orf controversy. 

archy diagrans, SAW Soler es. HID Guanes, and 
Mi J 


Others, nave seen the most 


a2 











usage ‘Ref. 51}. New developments such as structured 
program design languages (PDL's), automatsi1 graphic packages 
and abstract data typing for the desigi process are now 
being used tc supplement verbal descriptions of the software 
[Ref. 49]. 

The cencept of naturalnass proviies the reaier with 
EHO UNnEOLGing of information in an oclsred Warner. Sl 
smreowres that readers can verify they ate on the right track 
scam well ultimately find what they are looking for 
fexem. 52 ). 


2. Record of Design 


The secend objective of the programmer's maiatenance 
manual is to provide programnercs and manzgement a record of 
the philosophy of design andi historical jitvelopment of the 


softwar2?. The manual must inclide 2 concrcste representation 


(Dp 


of the software design as well. Glass ‘Ref. 43] Jtscribes 
£our catagories of documents which coul? b= included as part 


= 


Tenance manuel. 


Design notes explain how and why sections vz tne 
saftwars evolved into their pr2sent stats. They snasould be 
Meepe=-ie2n Scme SOrt Of standard format, etried chronoloqdi- 
meer y eme Cross=ancdexed to the progtan so1s. They do not 
have to be detailed but should odrovide 2 good overview of 
Pee GOnsepts supporting a oartisular desijga appreach. 
e PROBLEM REPORTS 

B@oueem SS p50 5S are Lesa ras of 26 eC encoun cared 
Mmiternemene Geoign process. They shouid describe the prebles 
S@ewics Ultimate solution. Diet CueVWea ually pDlasced 2F ee 
Seetarea= historic file once th finel ee ae wo LixXSd. Sosy 
eo eeeesmoly USsSecul ain iSolating Sstrors that ccecur during 
system testing. 

e IMPROVEMENT REPORTS 

Improvemenz reports are eee Crete te ane colilsctserns 
meee aecas hela fOr fLuturs Changes to be insotocret|ed into. zkhe 
SlftcWars svstem. They. can be m4 jor lmpcovenents or rosmetic 
Somes A Leeson for doing this 1S => pass ssund ideas cr ths 
B=S2qnerS to che Maintenance programmers. Thas¢e ideas maéy be 
Meerut when edding enhancencits as a tesul&e of changes in 
user's requirements. 


oye 





Version descriptions are nuabered chang2s ‘nat 
@=ser be the medifica*ions and sanhacncsmsnits added to 2 new 
Melease of rhe softwars Each numbered change should have 2 
complet list of the chang es #here they w2re made and why 
fewest OL the ee re Borts closed ani a description of 
the impact of the changes” on th usérs in the user's terms. 


The structure and description of the software system 
gd2sign is best kept as sinple and straightforwar aS 
possibis. Before the advent of structur2i prograaning and 
Structured design tocls (such as Program Design Laaguagss} 
Ehsre was no standardized manner <=> represent the software 
@2etgr. This is still a probisa today, especially when one 
desires to have "procts of correctness" to determina thas 
the software is frees of errors “Ref. 49]. The best that can 
memwen- 2s tO use 2 combinatio1a of items such as hierarch- 
Mest blicck diagrams to™list the Wajcor nodules ani ‘their 
egeemor7data flow relationships, gm@ouping of data item 
d2scriptions into "clusters" based on usajy2 of the data, and 
coding the desiaqn with a well organiz2i, modularized and 
readable high order language. 


Seeeoupport Maintenance Proyrammer's [asks 


The prograamer's maintenance maniai skould b 
Semoame document that programners need +> refer to for soit- 
Ware maintenance activities. The manual has to be 529 
miethctc ae must contain 221 the infornation needed by 
proqramners +O acc Onpiss sh = la uoc two  Obemal 
Sieeeoce 1g G€TZOrs (modification) and addiiag new ca; 


(enhancemens). 


To suppor: these <zasks the manial should be a weil 
Setenezeo, COncise 2nd thorougna description of the esttware. 
It mus* contain both an overall design view and a iiscret3, 


Q 
D 
§) 
f-4 
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Sete te1 procedure by procedurs view. It 1325 to desc 
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2 ane / 


asl 
daz2 items inputed tc the program (type/formac/e 
/ 


ants 


m 
2 ae 
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ho 
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processes performed cn tha data, ani the “*yps 








Monee of “the output data. In a real-tiis ntrol systen 
Wmeme the softwere performs coatrol functions base@ on the 
parellel processing of data, ene 1og=cal control caeponses 
to various data inputs must be specifiel. 

Data structure and organization 4as to be dascribed 
Bo detail. Enumeration of iata names, descriptions of 
tables and arrays and how they are ussi, Initiale zed or 


otherwise manipulated by the program is of primary impo 


pomerees Cross=teference listings, Which list e@eh Jata iten 
amawewery moduie, function 2an1 procsiuc> where that data 
item is used, are valuable 2ides for waderstanding the 
progtran. 


Finally, two general giidelines mast be kept in mind 
tf the manual is to support =he tasks 9& the maintenance 


Pesgramnecr. First, The manual must provide for somplet 


(D 


tracability from the user's oosrational cequirements to the 
Bommel pzsogram listang (lines wof code) so that @€ 2 r2audne- 
Meme changes then the approolate cole can be scsorrectiy 
changed, deleted or new code adied. Secso1d, «he ma 

bs easily modified and the chaajge recordesi oroperly in order 
mon Gberssct tne changes +o the softwaste. [f£ this is not done 
the manual socn becomes outdated and useless 

Geemete “Sci wm [ Ref. 43, 51, 33°) 


B. DEPARTMENT OF DEFENSE REQUIREMENTS 


How the cbjectives of 2 Raintenaac® manuai ace best 
mete oGg =s the main topic of this tna2sis. DoD currencly 
Beagur2es a copy O22 gene Pera arangu. .sc 2g and several 
SQopporting dcecuments for tepresenting ths program de¢sioan. 

yicemen 


p 

Ditferent DeD agencies have different r3g 

Meartation ard various names for in U 

Bop docinents briefly describ2i here ars from << 
an 


that describes a Program Maiaten 





agetiyities (DOD STANDARD 7935.15) and th5s2 U.S. Wavy stan- 


dards t2lating to software maintenance dortunentation. 


1. Program Maintenance Manual 


A description of the D390 requicenents for a program 
maintenance manual is presant2d in DID STANDARD 7935.15, 
"Automat ed Data Systems Dosumentatisa Standards," 13 


September 1977. Bne Standaras ( Maine oclsutatton ls towas 


fay 


Ay) 
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documenting large data processiig systens, however, itc 
Pemused TOL imbedded tactical sontrol systens 45 wall. A 
copy of the format for the Program Maiatenance Manual is 
providei in Appendix. A. 

Mecord=2¢q t> the standitad, the © Mai 
Oi 1S to be divided ints four major s2ct 
section is required to give a general i2s 
progrem; its purpose, history of devalospment, and define 
other documents used to support +th2 program (User's Manual, 
etc.). The second section contains a syst2m description to 
include applications, functions, input/output and informa- 
tion on summary reports. Details and characteristics of each 
procedure and subroutine toat would be of help to the 


Maintenance programmer are to 93 stated. Items such as data 


record types, table charact2crilsitss, skit end ~ SGakiemiag 
pmeGeddre=. -“nterfaces,. descriptions sf working ani output 
meres MESt be specified. The thitd sestion is to ilescribe 


the operating environment to incluie what su 5 
Geeemectca. This section is also t9 <tontain a complete 
d=scripticn of the data bas2? as well ass 


storage media for the data bas2 (tape, i: 


(4) 
ry 
. 


OL siaase = 7 pbs) < 
Mrmesoueen section +s to contain inforaation on speeclFic 
maintenance procedures. This will incluie information on the 
Page reng Oo: functions, subroutines and 4d21¢t2 records, along 


nos? 


feet he  OLOgramming standards 1%tii1ized. This section is to 
f 


i— 


Semeat a copy of the program 1istin 
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The Program Description Document (PDD) is rcequired 
by SECNAVINST 3560.1. Its purpose is td) provide a complete 
technical description of all proceiures, funetions, dace 
structures, operating envirdnnant, Sp@Eating constraints, 
and data base organization of the software system. The PDD 
is to describe and completely iefine th= basic program logic 
and projram procedures for 3aca system control subroutine. 
The PDD is also required to be directly related to the 
program design specifications whith are the formal func- 
tional requirements of the software syst2n. The PDD is, in 
essence, the Navy's version 2f a DOD s3rogram maintenance 
manual. ities PDDSdoeses rot CoOntesga a Sopy of the pregran 
listing or a complete data bas2= description. 


3. Data Base Design Document 


The Data Base Design Document (980D) is reguired by 
the same instruction to provid2 a complate detailed dascrip- 
tion of ail common data items necessary t0 carr a0 As iole 
functions of the software syst2n. Common data is defined as 
that data réquired and used oy two Or more sSubprodgrins. 
Examples of common data includ2 constants, indexes, flags, 
Variables and tables. The DBDD is to be based on the func- 
meonal ot performance Specifications. Ali terminology in the 
Meow 2ts to conform *o the prdqramming guidelines of the 
Peagcammecscign specification anid the parvicsulakc programming 
ieeeemaeg: ¢emp.oy2ed. The DBDD has t9 giv? an organized, 


Memaemed descripticen of all data Sbgjerts to include suck 
c 


ay) 
ct 
rey 
VU 


haractzrisitcs as purpose or tie Da2Ct,e ELeCld same, 


d+) 
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meyer orneric type (fixed pcint,  floatinj point), ¢c 
Eo 
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Peeeieceesnet alazed ccndicion. A cross-reference iistz 
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Sea (2d Oc me cdeumotce Jeo Cachn DrOgGram 
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Geach connon data 


Subprogram where it is used or set will b3 provided. 
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4. Erogram Package Document 


The Program Fackage Dosumeat (PPD) is designed to 
consist of all the program naterial items such as card 
decks, magnetic tape, disk packs or priated listing of the 
software instructions. The PPD is t9 inslude an ercor free 
listing of a compilation of the source program and any déta 
which is necessary for the projcam =o run properly. Examples 
of these data items wceuld be adaption data, data file cons- 
tants, set-up (initialization) data ani program paramete- 
values. 


>- Problems with DOD's Requirements 


The DoD approach, as standardiz2i in DoD SIANDARD 
7935.18, SECNAVINST 3560.1, ani MIL-SID-1579 (Navy) are all 
based on the supposedly "good managament practice" of havin 
tha maintenance documentation of a software systen be 2 
Pempoe.2 Set Of English text. Information concerning the 
program is compiled into volumes taiat, in complex systems, 
can reach several feet in width. All *nls text infscanation, 
as briefly outlined previousiy, gives a system overview, 
explains each item and structur? in the system's data bas2, 
shows control flow, data flow, nodule interfaces, and major 
mime ions. All this information, in and of itself, is u 
by the maintenance programmer. qowevec, OlaGung di 25 
Seperate volumes is not the bast way tod 
information is much more valuabl2 to ths programmers when 
integrated int <ho pheiskam Listing,  T. = 
Dcoumentation informaticn about a softwar2 syste 
=n most cases, ioe tang 6~6(llhfhaerth = phogra 
fRef. 53] There are three key reasons why documentation, <0 


the greatest extent possible, should be placed in the 
S 
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The Garst Gleason ts that progragiers tend to dislie 


Sale ab soy docunentation. They would emmush rather be writing 
code, which is what they do b2st and f22l1 the most comfor- 
table with (Ref. 54]. If the documentation is an integral 


part of the listing then using readable data names, jotting 
down a few lines of comment ¢25 explain 13w a procadure or 
function works and structuring the code becomes a ouch 
easier task. The programmer is savei fren the tedious 
p2per-work drill of having t) look up a separate progran 
Maintenance document, figure out how it's organized and 
where the needed information is and then submit a change 
Sutlining what program modifications or enhancements were 
made. The programmer can b2 nore produstive by combining 
two steps into one by keeping both tha documentation and 
program code up to date. Having the codes and documentation 
together can be used by manag2rs as a ndtivation fastor by 
dz2monstrating less work for th2 programmers in the long run. 
Other benefits can be shown’as in th? case of using 4a 
programming team to develop a Large software project. Here 


the teaa can design the documentation as they design th 


iD 


PEee@uGceine Of =he Software. This can elininate ‘the neaai for 


$v 


Stperat= team just to design and write the documentation. 


The documentation design can be directly relatei to and 


Supportive of the software design. 


(b 


MitemsecOnd Erecason £2t olacing G>Sumentation in <h 
A 


listing is tc enhance manag2ments spaa of control. 


(A 


Meniicned earlier, there is a large requirament for nanagse 


ie 


v) 


t> keep a big-picturs view and be apie to Supervise, direct 
amc tras pregrammer's activities and progress while they 
ace performing maintenance tasks. Pees Uosinencatcion 26 oe 
listing prevides ‘the means whereby a naiager can evaluects 
changes to «he software and its resultant quality. Managers 
would no longer ba required to evaluat? changes to the coda 
ees) associated dccumentstion 2nd <th22 heve to check to 


5) 2) 





make sure the documertation shange corrasctly reflects the 
code change. In essence it is desired t>» avoid a "diouble- 
entry bookkeeping” system wher2 tha docunantation dascribes 
the software as the managers ani programm2rs think it works, 
and the listing represents how the software actually works. 
(Ref. 53] 

The final reason is that a pceogram maintenance 
Manual nuSst remain accurate ani valid as long as the soft- 
ware system is useful. Progranaers must be able +9 quickly 
logically use the documentation to understand what 2 section 
Semcoae 1s eccOmplishing and how it is doing so. Again, if 
user's requirements change, it is essential that the soft- 
ware be changed rapidiy and in an error-free manner as 
possibl2=. If a maintenance progranmer cannot tell how the 
code is working, changes basei on valiji user needs, or for 


ay MOmRec EeaSon, will be difficult at best. 


C. A PROPOSED "IDEAL" MAINTENANCE MANUAL 


Tomevercom> the Gitfticulti2>s with upiating the docun¢en- 
tation and ensure that the dotumentation is in a foctm thar 
readily usable by programmers and managers forces one to 
sider a revised format for 2 progran naintenarce manual. 
¢ manual contents presented here are based on the ad 

Mofesanhhetenet woth tne quality ard detail that th 
Standards require ard those advantages gained from in 
Mereno current Softwares engidesrcing pracszsices. The "Ide 

cogram maintnenace manual will be divided iat <£9 
moe ( 1) Overall) Program Structures, (2) 


O 
Canc, (3) A 6 (Dees Dleet onary, ara C4) 5 








1. call Program Structuce 


The overall program structure should consist of 
words aad pictures indicating how the entire system h2ngs 
together. hunetional block liagran, which shows all «major 
modules, procedures and functions is esssatial. This diagran 
r2presents the system structure, ene) sk acutionm™ ofder (if 
possible) and data flow. The section should contain a well 
organized index, logically arranged, which points th way <o 
detail level documentation in the listing. The index should 
ceflect the block diagram and the design of the svst2m. The 
index should locate major data structures and data clusters 
within zach module. This section should contain a4 written 
text introduction to the overall purpose and function of t 
sottwar2, the hardware configuration used for tests a 
evaluation prior to software delivery, and the targ? 
computer system (tactical or iata processing) the softwa 
meme Of. bach module of the progran will be listed, 2 
Omemer d=Scription of the module given and the function 

elaticnships/interfaces with other modules conmplece 
annotaze 

ey. the cection Sshauld state th 
r2sponsible for the program i=sign ani dev 
names of the chief programmer and members of his t2am and 
apolicabie references and staniards use2i. These =randards 
should include the program performaice sozcifications, stan- 


Seeds £Or data objects, ani the language programming 
a 


Bo WW esehereey i) Ib sbsye nd el 


The computer progtan Sts? 


Ng 
mipercaae cCcol for SOT“ war> tnainten 
opjective or the maintenance manuai is 

in 


muEmepwi cy aspecs> Sfs the listing. 
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ae eritiviid cy are “fo be emAphsized over Ssfficiency. “It is 
MmrpOLcaht thar the program listing be clear, conciss, struc- 
tured, well designed, modularizead ani straightforward. 
(Ref. 48] Each module should contain a description of what 
the modiule does and what procelures or functions are 
contained in the module. Bash modula should contain 32 
section for data descriptions or declarations, global and 
local. Table, variabie and flag diclarations may b2 segre- 
gated and logically grouped. 


ae Physical Layout 


GOodmpnystcal Jlavou. is disfined as “...chat 
property of a program listing which makes it capable of 
being read and understood by 3 programmac not familiar with 
the program." (Ref. 48} Gooi raadibility nay be achieved by 
a variecy of techniques, some of which ace; seperation of 
logically related groups of coie, separation comments and 
EGS , biocking (by uSing lines of asterisks) lengthy 
comments, the appropiate use of blank linss, logic3l inden- 
ma —t2On 2na the Linhang up Of bDezyin-end, if-then/else pairs. 


Aion (ene mts DE Ser eceNLSi DrOgrammiag , as 


( 


Giscussed in Chapter III, ace key ingrediants of good 
Physical layout. Paqteccmm Nooo Gn S45 Lilustraze this 
physical structure. It may be imposed on the code, as with 
assembly language, or be part or the linguage syntax as 
with ADA. (Ref. 38, 39, 42} 
b. Commenting and Namiag 
The use cf meaningful commerts is of prinary 


lmportance to ite Getse SUNG aScand nq 2 me DpDtOgna ln. 
m 


d 
Comments should explain, amplify and supolement the Listing 
ro2xa 


Eawmemmcnenm echo the code. F mole 


N=N + 1 --[rcreament N 
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; 
| 
| 


$$ ----------- 


-- A message has just been inserted int> the message | 

-- gueue. 

Poet nce Mente Nag QURUE PO@ntsr so that it points™to | 

-- the location Where the next message nay be 

——=wenSerted. | 
| 
| 
4 


Msg_JUEUE_Pointer = Msg_Queue Pointer + 1 


Coe ee ee a i 





Figure 4.1 An Example of Meaningful Comments. 


doés nothing to explain why N is being incremented. A better 
2xample is illustrated by Figure 4.1. 

T£ a program moiul2 consists of more than cne 
procedure or function then thace should be commentary for 
each procedure or function. The comments for each procedure 
and function should contain an 2xtensive, detailed iescrip- 
tion of how the procedure operates ani its purpos= in the 
module. The sequence of processing should be described in 
Seon clog=-=cal Order  cO include the calling sequence of 
Sene=Ol, The hierarchical sertucture) of the modules can be 
reflected in a like manner 2S zomments Follow the ohysical 
Meee nttat2on. faobe ETie)=sts Sher “eritecia for commentin 
as discussed earlier. 

All names for data objects, modules and proce- 
dures must be descriptive in nature. They should attempt to 
embody the characterisitcs of the data item they represent. 
Names such as ID_Buftter, SINE_Function ani 

=nherent meanings and are easiar for the programmer to trace 
mimpomgamere iisting. Names such as 4, X, VN, or XYZ are mean- 
~agless. Related data items and procadures should have 
reiated names which demonstrite their interconnections. 
Pee Gaye Od; U8 7 





Gow BlcweamDeC bagatiions and, Dafinitions 


All data items should be grdip2d and organized 
according to their logical usage. S$lobal data e3lements 
should be derined in one location. Local data elements are 
t> described in the procedure where they are manipulated. 
The technique of information hiding, wharcs the structure and 
characteristics of locai data 22d paranstears are unknown to 
procedures in other modules (Raf. 243, is to be utilized tc 
the maximum extent. 

Iz the programming language does not support 
Strong data typing for data declarations, as in the DOD high 
order ianguage ADA, then variable, tabl2, array aad other 


data deciarations must contain meaningful comments. These 


(t 


comments are to describe the purpos?, initial valu2, range 


SmdeGd2stinrGt  Structum= Of 2ath data element. Figure 4.2 
2) 


m 
reveals how a data tabie (or r2cord) would be declared in 


—— ges sa = la ial guummammmmmemamaaints: 
| | 
| | 
| type MONTH NAME is (JAN,F=EB,MAR,AP%,MAY,JUN, | 
| UOC o er, ICl ,NOV, DEC); , 
| 5 
| type DATE is | 
| record | 
| Ors (NPEGER Geage 1. .31; 
| MONTH: MONTH NAYS { 
| YEAR: INTEGER | 
| era Seeor ad: | 
| 
| 
Be a a et a J 
Figure 4.2 Example of an ADA Data Table (Record). 
ADA. The table is called 'DATE* and has three conponents 
maeeag pay’, 'MONTH', and "YrAR*'. DAY ani YEAR are definec 
eo Demet type INTEGER. MONTH has @ ssperate type ieclar:- 
Biemmeeenca NONTH NAUE, INTEGSR its assunei co be defined bv 


o4 





the support seftware of the system and having the mathemat- 
isal characteristics cf all integer numb2rs. Variables and 


constants associated with tha table JATE can then be 


i aries are oe Te eee ee 7 
| 
| | 
Comment | 
| TABLE accoUNTS 
== USéed to store information on 400 Bank 
accounts. Consists of four tiz2ments. | 
| 1. ACCOUNT NAME (ACCINAMS) | 
———Ceneains wo to +0 NocLL Ghat ace | 
| 2 mca NUA BER (ACS TNR 7 | 
| -— Ranges fotn Zero to 39999 and is 39: | 
7 humeric typs INTEGER. : 
{ 3 Bees (ea LANe®) | 
Renges £aan ~9999.99 t¢5 9999.99 
del ars ani is of num2ric type | 
| REAL < | 
| a. PEAS TLE), . 
| Aol ho (= "Ibe AGecoult 2S Xn Use. ‘ 
| When False (=0), AcrtoOunt 1S not in \ 
| seats 95 Logicai ty2s BOOLEAN. | 
{| Miscellaneous , eee . | 
| == At program initialization tine the 
| entire table is flushed (s2c_t5 ZERQ). 
Wideeos (OemOoOln soa ol gelatsl to this | 
( table are the nam2i variables LASTACCT, 
| NOX MACeT 2nd NEWACS T. 5 7 
{ TABLS ACCOUNTS V DENSE 400 5 
| Paneo ACCT Nams HH 20 5 | 
FIELD ACCTNR I 14 3 
| Bee SALANCE “A 22 5 7s 
Piero ACTIV s B 5 
| END-TABLsS ACCOUNTS | 
[ | 
a ccs ee ee nee es a foe ees eae Glee eee cae seinen ca ene eonssieubencaneamaeanambass oan umn anna aus ann ot 


Figure 4.3 Example of a C¥S-2 Data Table. 


defined. An example would b2 a variabi2 aamed 'D' balongin 


eOowcyoem JATE. Before 0D 1S US2qd OF initialized it must be 
d 


EQEthner Getined. This is dona by by NGDibewec a 2 GOT 
followei by the component name as 22:3 Chaat f= fd) 
eerie =e JUL) >, ahd (D.YEBAR:= 1773). Ie 2s cl#er that all 
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the attributes of the table called DATE acs readily apparent 
to the naintenance programmer. The readidility of 2ach data 
SpjeCc2 Ciarifizes the purpose and structure of th= table. 
[Ref. 44] Figure 4.3 gives an example 2f a common way <o 
declare a table using the Navy's CM5-2 programming language. 
The us2 of clear and consis2 comments fulfills similar 
objectives as data typing in ADA. 


She 


| 


Data Dictionary 


( 


MedceammonccLCnaky provides descriptions of indivi- 
a 


fou 


1 dat 


u Sntataes and Can besasedeas an index as t5 where 
he data elements are declared in the projram listing. This 


) 


ct 


Ss extremely useful for larg? orograms, i.38., or¢eater than 


fowoou lanes of code. The data dictionary can and should 
Pmovede =ne froOrMats for the declaration of data within the 
program while being a catalog of the data resources of 3a 
software system. (Ref. 55] 

The data dictionary defines the P52 Ca leer d ateze = son 
and physical organization of t12 system's iata entities. The 
logical organization specifies requiremants for data accéss, 
Med2tication, associativity and other system orientated 
Semecerns. tne Physical organiziaewen defines file structures, 
rscord formats, hardware depenient proc2ssing features and 
databas= management characteristics. All lata structures and 
the operations that are to b2 performed on e2ach structures 
amen oec "Gentlited in the dzstionary. Che program listin 
can be rzreferenced for detalis on data 2lements and those 
runctions or operations dependeat on these elements. aA daz2 
dictionary can explicitly represent the ralationships anong 
deeecames, the cCOnStta:nts these selemeants place on data 


Sealciwe es. Algorithms that nay take advanzage of SGaee 


0 


bh 


ta relationships can be mors easily designed and nodifiscd 


ip 


2 
Bamcmece Mona vy=ii ke data SpeclLiication ax*sts. [Ref. 56] 





ihemecoaaPUGOpeate that She data  dicticnasy ceflect 
elomeeclectmice Of the program listing as closely as possible. 
Mmem concept of "mapping" the dictionary ontd the listing 


ensures the consistancy requir2i by maintenance actions. It 


b- 


S critical to the maintenance programmer to know which data 
items effect which particular modules ard vice versa. A 
carefully designed ard integrated data dictionary is an 
essential tool for any modifications or 2nhancements to the 
softwares. 


4. Appendices 


This section of the maiatenance nanual is to contain 
that supplementary informatioa which is of a historical 
nature. Examples would be notes on the development of the 
Software design, problem reports and inprovement reports as 
described by Glass [Ref. 43}. In 2 seperate appendix could 
b2 a conplete description of ths intended sparating 2nviron- 
ment, hardware configuration and »perating system support 
dasired or required. A continuous fils of each version 
release and a log of ail chanjes nade <5 the program (who 
made «them and for what r22son) shauid be included. 
(Ref. 40, 42, 48] 


AD fare! appendix should contain 32 set of standards 
for cohmenting, Skgeus nie Co oeatle ruras, and tha data 
ict LONALY. The standards foc commentiag are usaful for 


Sen sesSrancy nd *9 enforce reedio 

Seaid@asd aigOrithmic Structures provids a framework for ins 
develcpnent of module librari2s. Siem Labreries can. oe 
Meewrezei => edd SnhancementsS tS the program in 2 short 
baricd of time since the modules involved ars already tested 
BOI onsenmr Tee COEratlOn 2rd ths functirans or services 
providei by the module aze weil known. Standards for the 
ae des 


Wiehe ty, PlLOVIe “Comin interfaces betw2a2n “the 
a 


67 





accomp ished by specifying the flow and storage locations of 
data entities within the organization or within the computer 
installation (Ref. 55 J. Standards for a jJata dictiosaary can 
also provide a library of staniardized jata structure temp- 
lates +> be used for representing the lodgical and physical 
Characteristics of data entitits within the software systen 
database { Ref. 56]. 





V. CONCLUSIONS AND RECOMMENDATIONS 

The Department of Defense has an urgent requirement to 
reduce the costs of Software nainteéenance iuring +h2 coming 
decade. Recent advancements in the asthods cf software 
engineering such as modularization, Stluct@meed design, 
structured programming and data abstraction have contributed 
to greater program comprehension. fhis increased conprehen- 
Sion leads to easier modifications to neert a dynamicaily 
changing environment. 

ttrsetre —sepan.cn Of this author that the benefits 
obtainei from proven softwares 2ngineering practices can be 
realized in the pregram maintenance manu2l. These principles 
can and should be applied to the iesign and standards for 
such a manual. The information availabl2 strickly from the 
program code itself forces us to guestion the practice of 
keeping the decumentation seperate rrom ths codé, ani leads 
~omeune SCORCLUWS-0n that it shoulad not be seperate but 
integrated into the Listing. 


22h this in nana =he fsildwing reconmendations 2re put 
morth: 

ithe DpLecent standards £96, softwace documentation be 

revised to incorporate the most useful aspects of 


resent software engineering tecthnolojy. 


e studs es should be undertac2n with ths goal of stand 
-Zing Terms NOS QverOt ee soEtware Maintenance id3c5uR 
among ali DoD 2c tivities. 


e A framework has reen proposed for 2 o9rcgram maintenance 
Mmanuai. This framework shoaid _b? _implemenced and 
rested ON various size ani types of software systems <o 

scover what savings i2 time and money can ds 
2s eved. 
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SECTION 1. GENERAL DESCRIPIION 

1.1 Purpose of the Program Yaintenagc2 Manual. his 
parajraph shaliI describe f€he ~ purpsse dort the 4AM 
(Projram Maintenance Manual) in the f5lLlowing words or 
apprdIplate modifications thearato: 

Meee OD jective =20r wWliting this Program 
Maintenance Manual for (Project Nans) (Project 
Number) is te provide *13 maintenaicss Eos some 
persornel with the information necessary fo 
2ffectively maintain ths system. 

1.2 Project References. Dai sipwcagraph shall preovids 
a Driet summary Of the references a 2Caple “fo che 
history and development of the project. The general 
Mature or the system (tactical, inventor COME ont 
a a management infoecmation peer), developed 
Shall be specified. A brief iescriptiona of this systen 
shall include tS purpos2 and usés. Also indicated 
Shail be the project ¢ponsor and us2r as well as the 
operating Font soe chat will run the completed 
COmputer programs. A list of a plicable docunents 
Shail be inciuded. At least the Following shall bs 
specified, when applicable, bveeale too OF  SOlECEe, 
reference number, title and security classirication: 


a. Users Manual. 
b. COmputer Operation Manial. 


Cw Ceues PeSLTtInert gee umente=:50 on <he 


pro ject. 
ieee uoete ata Abb teWwi eri ons, Pio oab ace a ph sie tt 
oe eens Por eite Mids eed aeppslidix any@escms, 
Ciel eeon> Of SacrtonymsS Wnigue co this document and 
Subject tO in=erpretatzon by the user o£ the docunent. 
This list will not include 1tem names or data codes. 
1 


= 


DED OE! ET A cee i ee ee ee eee 
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SHCTRON 2. SYSMBR: DESCRIPPION 

2-1 System Application. fhe te 2E the ae en and 

the Functions Tt performs sha 1 2 eee ee Ba oe 

cular applicat: on system, for example, ight set vs co 

oe mission ages 1és by accepts ng svecific 
uts (sta*us SROs eS, emergency conditions), 

ex racting items of ata, aad deriving other 1L=eas Of 


data in order to produce both infoftmation about a 
eciftic mission and information for summary Eee 
T es2 functions shall be ra2lated ea aC ae ar 
Specific Perificrmance Requ- ir2ments 5 Br Systah 
Functions, of the FD (Functid nal Dés- Si aet Gane 


2-2 Security and 
descriceée the class 
me lie ng Tes 

programs. [It i£1 
ticns Beociaa wit 


FeVvasy. This ara ale shall 

Components df SYsStemn, 

aye e bases, ea computer 

rib= any privacy Eestric- 
F the data. 


pO 
mis ByrO 


2-3 3¢€neral Description. This par agraph Will ppovide 
a cone lence aae desetiption J£ tas ices , subsysten, 

jobs, etc. in terms of theic overall functions, This 

escti sption will be accompanied by a chart showing the 
interrelationships of the anajor conponents of the 
SySt2m. 
2.4 oo DGS eo er MocmourOOS> Of this oara- 
graph is to Seay Bee eee omen tase b 2 Stacs 9£ Sach 
program and subroutine that would be of value toa 
maintenance programmer understanding the progran ne 
Hos Be ac Chichi Pmeerotne: Programs. (Spe cial maint 
nance programs related t5 the specific svsten Deing 
documented, will be discussed und2r paragraph 4, 
Special Maintenance procedures.) This paragraph air! 
=pitially Con sosieea fst Comall programs t5 be 
oles scussed, foilowed DY a@ Aaccative description of each 
program and its respective subroutines under se 8 Sr alae 
pe aragraphs Sane ang O2ry. 2.26 1 a= Og 1. Vale 

Se oeRae? on to be included in the narrative descrip- 
tion is represented by the following itens: 

a eee Pee SoOg ccm gumbsb Sf tag 
of th2 version 


ecards designation 

humber the program. 

Db. MilmCc=ions >= description Gf program Be Cee C 
and method USedma ths Progtcam &t> accomoli 
eer News OL. 


Cee SSG Pp 1Chn ot) eDesiapuc. Descriptions 
Meee G@USt tnsiude ail iniotmatisn pertinent to 
Maintenance progrs eats renewal 33 $ 

(1) Data records usel by wae eprogsam during 
Geors 2190 

(2) input data type and iccate 22(S) used by 
the program when its operation begins. 

(3) Entry requirements concerning the 
initiation of th3 prograa. 


2 


> ee: ee ee ee: ee ee oe eee 2 ere TT oe SS 


lec 
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(1) 


(2) 
(3) 


a a 


(4) 
(5) 
(6) 


(7) 














1d. Processing - description of the processing 
performed by the program, incluiing: 


Major operations - the major operatiors of 
PEOQctam wali be jescribed. The description 
May reference chart(s), which nay be |. 
included in an Sp Pegg: Dil shGmart well 
Show the general Logical flow of 

Operations, such as _ read an input, 

aGe= somo dcpeecmessoEG, Manor decision, and. 
crint an sutput wnich would be2 represented 
y segments or subprograms within the 
program. Reference may ba nade to included 
charts that present each aajor operatioa 
in more detail. wee 

Na gee sO canenming Someitions provided in 

the program. 
Restrictions that have been designed into 

the system with respect +> the operation 
epee jilal is Bee 7a ay Se any Linitaevilons on 

the use of the piso ae an - 
Eto c Gt ketewrs COneCENIAg t2EMinatlona 
of the operation of the projran. 
Communications oc linkage t) the next 

ee Oa Peegrateteperaclonal, control). 
Output data eee and Location(s) 

produced by th2 program for use by 

related processing segments sf the 

sys 7em. 

Storage - Specify the amount and type of 
storage required to use tne program andi 
the broad parameters sf the storage 
locations need2d. 


SOuCpUL - Aescrageion GL the Outputs produced 
DyeeveeDoOGg ra. whllS Enas GSssription nay 
reference output described in tans Users Manual, 

Sn ceemediate O@tput,Mworking files, sts. 
should be described for the bensfit of the 


maintenance programmer. 


fF. Interfaces - description of the interfaces to 
ELOT wns .p SOG ale 


| 
| 
| 
| 
| 
| 
| 
| 
| 


J. Tables and Items - provide details and eee 
Cidpde toes iGo OLeths eaoles 21d items within 
each program. Items not part of a table nust 
be listed severately. Items contained within 
a<zable may be reteranced from the table | 
ese we Peel 1 bat oeoataeaescrui9tion of Ehe 
BLOGEam PrOVides SWEEL Caent infdctnation, che 
program listing may 52 rsterencsd to proviis 
Some or the necessary inrormatiosn. At leas* 

3 


ths, 


Ee a | 


iG comtiiiate <euiain <i A ON ee OE cae ES a een, A ei eee i a A ae AN A iS A ED aD a TS OTS i aS NS ES a ee ae) aemeiene 


| 
| 
| 
| 
| 
| 
} 
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the follow 
Tabl 
Full 
Othe 
(4) Logi 
(ant 
entr 
(5) Basi 
leng 
Stru 
Tabl 
shou 
desc 
“io tate: 
each 
char 
and 
loca 
item 
spec 
that 
mani 
sens 
mach 
than 
2mpo 
of e 
will 


| 


Unique Run 
unique fea 
ie te) oe Meares 
Omputer OQ 


wh 


(6) 


(7) 


= 


D 
C 


ie 





ee 


ing will be included for each table: 
Ll} name. 
table. 
table. 
table 


e tag, labi2 or symbo 
hame and purpose of 
cr progra@s that use 
cal divisions within 
erinal table blocks or 
eS). ' 
Cc table structure (fixed or variable 


cr Ere 


ene 





th, fixed or variable entry 
cture). ; 
2 layout f 2 SSeS Clee. O10 
id be used). Included in supvorting 
Eapeeomesmould De tadls comecrolling 
Mia om Uta. 1s Of ohs Structure of 
type of, eatry, Unease OC Sl gneiss nt 
€aCCSristics of the us2 of the <able, 
Xnformation about the names and 
SoS tOr 1t2ms within the table. 
Peet heecos tm cml TerSoss tO. 32 
MeicmeceegonyYsormGctarliocd 2npfosnatior 
1s coded £54r direct and immediate 
Pll eesOnwoyua Progeam. Used in this 
Cgc wemooretatson Of #18 2tem is 
ipe- ana PGlGmam-Orisated rather 
operationally oriented. Of primary 
rtance is an explanation of the use 
ach item. At least th2 foliowing 
be included for each item: 
teem tages: vipel aydi full name. 
Purpos? 9£ the iten. 
[tem coding, se upon the 
1tem typ2, Such 25 1at2ger, 
S¥MDONNC, ‘Seats, 2: Sc. 
Features - destription of any 
Pee SO; wri oINn e@ gel f this 
(iene Nowene lided £21 the 


peration Maauail. 


he tes cement cote ame TN ee te ee a i A ES ES EE oe eS ED EE ete comp Se cate EE Ge cottage GOP aap aOnEEp cilia EERE gees aap MES co oot See anes coe ew ae eS i 
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SECTION 3. ENVIRONMENT 





oe eaten ea eonments This  oaragraph shall 
discuss the quipment configuration and its general 
characteristics as they apply to the syste2n. 
Gaz) > pee. Software. chs pew 222 Shall list the 
Various Support Sottware usei by he system and iden- 
tity the version of releas2 number andier which che 
system was developed. 

S.oube dad) Base. Information in this pare SEARS shall 
incluae a complete description of the nature and 
content of each data base us2d by th2 systen. 

3-3-1, General Characteristics. Provide a general 
description of the characceatistics of the data base, 
melding: 

a. Identification - nam2 and mnemoaic reference 
Of the component (3.3. data base). List <h3 
peed teas cea 2eno elomecOmpoOnent and explain 

he use of the component in the system. 

b. Permanency ~ note whether the component 
COUscrtseceatme Gatd that a Program can. 
reference, but may not change, or dynamic 
data that can, be changed or updated during 
System operation. [Indicate whsther the change 
Boece nOahe Of Ganaomg aS a £UARStion of input 
data. 

Soe OLAgS = oes the storage media for the 
Gace Ddecm(e.G. tape, Gack, intetnal storajz=2)} 
and the amount of storage required. 

1. Restrictions ~ explaia why linitations on 
the use of this conpoient by th? orogram in 
the system. 

3-3-2 Organization and Detaiied Dessciption. rhis 
Dtactaepcieisis Pocono ahve e ene Ihlerual Structure 
of the data base. A layout will b= shown and its 
Geupos2tlon, Suen aiSe, bsecotds and eibies, will be 
Smuetewed. fr avacalable, SompUEGCE Janerated or other 
meoeugs er ehis deta led ~intrormationa may be refer- 
enced or included herein. Ta2 following items indicate 
the tyve of information desired: 

Peta Cite snot ene stolewube Of tho data base 
PHeGaUd=2G cSGord and -1 tpeus. 

Dee CeZONS - ROte Whether 21s Physical record 
Mec Legl’Cal ~ecOrl of Sus Of Several that 
Gepotecicte a bogieal eecord. Lientify the 
Peon Mesus, suet as Neadl-=r 5= Sontrol 
Segments and the body of the r2csord. 
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Ceeeimetds ee 1dcrtify@each field in the record 
Structure and, if necessir4ry eOLain itS purpose. 
Include for sach fielj tie 2 Elpmane items: 
(1) Tags/labels - indicate the tajz_or label 
assigned +9 reference each fi314. 
(2) Size - indicate the length ani number of 
ee eer ers that make up 3acho data 
Le 
(3) range -_indicate th2 range of acceptable 


Xx 
values for the fieli Gh. ivi 


d. EX énsion = OPC previ Sons, if aie BOG 
adding additional da*t3 fislds t> the recor. 
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SECTION 4. PROGRAM MAINTENANCE PROCEDURES 


Section 4 of the manual shall provid information on 
the specific procedures necassary for the programmer 


tO Maintain the programs that make up th2 systen. 

4.1 Conventions. This pacagraph will explain all 
rules, scnemeS, and conventions that have been used 
WamuEn the system. Information of tais nature could 
include the rollowing items. 

a. Design of mnemonic ilentifiers and their 
opi iCaeden! tO. The tiagqcng or labeling.of 
prcgrams, subroutines, resords, 312*4 fields, 
Storage areas, etc. 

Deh SOCcamines "and Stamdacds for charts, listings, 
Sori dimezatwon. OL Caris, ebbreviations used in 
statements and remarks, and symbols appearing 
in charts and listings. 

Semi vcme nop wetSe srdndimds, fully tdentified, - 
may be referenced in lieu of a istailed ouline 
or conventions. 

d. Standard data elements and related features. 
ee cies cactol, POOCeAUESS. § THiS patagraph will 
include those requirements and procedures necessary +9 
check the, performance of a program Scr ton foliowe ng 
Mes SOterescaceon., tneludsd say also be orocedures for 
Che Beomrogd=.=¢ Veriisication of the projrafti. 

Je oeeor COndii20ns. Reena Sep Ptioy Of error condi- 
rons not previousiy, documented, may als> be 
included. Rigor eeocer oe voleoamalt 2NCLude 2n explsne- 
Plot mmOrem Ger, SOUTCe Of the crrst and recommended 
methods to correct it. 

Hou Special Maintenance Prosedures. WILE eles vo fig 2.16) 
Shalit contain any special a a required which 
have not been deiineated elsewhere in this section. 
SPeCr are =peOrMacton. that mey Dee a0REODla=e] LOL 
presentation shall inciuds: 

4. Requirements, porcedures, 2nd virification 
which ma y be necessary to maintain the systen 
inpu*-output components, such 423 the dat3 
base. 

b. Requirements, procedures, and verification 
metnods necessary to perform a Liorary 
Me=ntenance System Zin. 

Ws2..spectel flaintenance Prograns. PhS paragrapa 
SeeeemecoOnca:N al GhVERTOLY Of Any Soecial orojrams 
(such as file faestcration, DUietengeaastoOlLical £21¢€%s) 
used to maintain the systsm. These ee acs should be 
described in the same manner as nos described in 
PasagGdens 2.3 and 2.4 of the MH. 
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a. Input-9 ut put Reguiranents. 

Included Syeewch is palagr amen Senall oe the require- 
men=s concerning the equipment and materials need2d =o 
Support the aa! Malntenance tasks Materials 
may, for ¢xample ~ncelud2 card decks for lo@at ng 2 
Maintenance rogra a and the inpuss whi represent the 
changes to e made When a support system is being 
used, this paragraph Should reference the appropiate 


Manual. 
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Db. Procedures : 
The procedures peengeecs nia. 
Shall detail the me 
as structuring 3 
tions or steps to 
and terminating ¢t 
Shall be given. 


by7;step manner 
2 ahs 1 Ob re Suc 
Sr. The 2oera- 
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a the equipment 


d 
be followad in s 
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Eon Seings. 


iis Paneadrapnme Wiil Sontain or 
Tererence =o ¢ 
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BaVeads 
location, of the, program Listing, 
omments a propi eas 
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Cc [Or PpAacTcWwewar iLnstructions 
eget bade Bt nec 


Sary to understand and follow 
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